Add listing photos
Current Home
Add listing photos
Append photos to the caller’s current-home listing (max 10 total).
POST
Add listing photos
Overview
Attaches one or more previously-confirmedHOME_PHOTO uploads to the caller’s listing. The combined total (existing photos + the new batch) may not exceed 10. If the listing currently has no cover photo (i.e. this is the first batch attached outside the onboarding flow), the first photo in the batch is set as the cover.
Each uploadId must already have been confirmed via POST /uploads/confirm and must belong to the caller — server cross-checks the uploads row by userId.
This endpoint is reused after onboarding step 3 to add additional photos. During onboarding it is not used — step 3’s POST is the dedicated entry point.
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values / Constraints | Example |
|---|---|---|---|---|
photoUploadIds | string[] | yes | 1..10 entries. Each is the uploadId returned from /uploads/confirm (24-char ObjectId). | ["66400a8f1c2b4d5e6f7a8d01"] |
photoMeta | object[] | no | Up to 10 per-photo display-metadata entries computed client-side after cropping ({ uploadId, blurhash, width, height }). Keyed by uploadId; entries not referenced in photoUploadIds are ignored. When omitted, photos store an empty blurhash and 0×0 dimensions. | see below |
photoMeta[] object
| Field | Type | Required | Constraints |
|---|---|---|---|
uploadId | string | yes | 24-char ObjectId; should match an entry in photoUploadIds. |
blurhash | string | yes | BlurHash placeholder string, 1..120 chars. Painted by the app as a progressive placeholder until the full photo loads. |
width | integer | yes | Cropped width in px, > 0. |
height | integer | yes | Cropped height in px, > 0. |
Example payload
Response — 200 OK
Returns the updated Home object including the appended photos.Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | photoUploadIds empty, more than 10 entries, or each id fails the ObjectId regex; OR the batch would push total over 10 photos. |
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 404 | NOT_FOUND | The user has no current_homes listing, or one of the uploadId values does not belong to the caller / does not exist / is not a HOME_PHOTO. |
Example error — 400 (too many photos)
Side effects
- Appends new entries to
current_homes.photos[]withorderIndexcontinuing from the current last + 1. - If the listing has zero existing photos AND no cover, the first photo in the batch is set
isCover: true. updatedAtbumped.- When
photoMetais supplied, each photo’sblurhash,width, andheightare stored from it; otherwise they default to""/0/0. - Enqueues an
image.processjob per new photo (stub in Phase 2; Phase 7 generates thumbnails, EXIF strip, and can backfill a server-computed blurhash when the client did not supply one).
See also
- Reorder photos
- Set cover photo
- Delete a photo
- Confirm an upload — must run first.