Reorder photos
Current Home
Reorder photos
Update the orderIndex of one or more photos on the caller’s listing.
PATCH
Reorder photos
Overview
Updates the display order of photos on the caller’s current-home listing. The client sends a list of{ photoId, orderIndex } pairs; the server $sets each pair atomically against the embedded current_homes.photos[] subdocuments.
Every photoId in the payload must already exist on the caller’s listing — unknown ids return 404 NOT_FOUND. The cover flag (isCover) is not changed by this endpoint; use Set cover photo for that.
Partial reorders are allowed: photos you do not include in the payload keep their existing orderIndex. If you submit overlapping orderIndex values across photos the server still writes them as-is — the client is responsible for sending a sensible permutation.
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values / Constraints | Example |
|---|---|---|---|---|
order | object[] | yes | 1..10 entries. See OrderEntry object. |
OrderEntry object
| Field | Type | Required | Notes / Constraints | Example |
|---|---|---|---|---|
photoId | string | yes | 24-char ObjectId of an existing embedded photo on the caller’s listing. | 66400a8f1c2b4d5e6f7a8d01 |
orderIndex | integer | yes | 0..9 inclusive. Lower = earlier in the gallery. | 0 |
Example payload
Response — 200 OK
Returns the updated Home object with the newphotos[].orderIndex values applied.
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | order empty, > 10 entries, a photoId is not a 24-char ObjectId, or an orderIndex is outside 0..9. |
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 404 | NOT_FOUND | The user has no current_homes listing, or a photoId does not match any photo on this listing. |
Example error — 404
Side effects
$setsphotos.$.orderIndexfor each pair on the caller’scurrent_homesdocument.updatedAtis bumped.- No
image.processjob is enqueued (no new bytes). - No
match.recomputeis triggered (photo order does not affect matching).