# Property listing photos

Owners manage listing photos in Console → Property → Listing photos. Add up to
10 photos, crop to 16:9, edit descriptions, reorder, then **Save photos**.
The first photo is the cover. Existing covers are retained as the initial photo;
website slideshow/general-gallery photos are separate and are not copied.
Unchanged older covers are preserved without forced recropping.

## Owner read and save

These routes require a verified-email owner session, not an affiliate API key.
Upload through the console's existing image uploader; the API accepts only
property-owned listing-photo/cover paths and verifies actual image dimensions.
Descriptions are at most 1,000 characters; optional groups are at most 80.

```sh
curl --fail-with-body --include \
  'https://api-preview.wikiup.app/api/properties/property_example/listing-photos' \
  -H 'Authorization: Bearer <owner-session-token>'
```

Copy the quoted ETag response header into If-Match. Keep existing photo IDs;
omit id for a newly uploaded photo. PUT replaces the whole ordered collection.

```sh
curl --fail-with-body -X PUT \
  'https://api-preview.wikiup.app/api/properties/property_example/listing-photos' \
  -H 'Authorization: Bearer <owner-session-token>' \
  -H 'If-Match: "etag-from-get"' \
  -H 'Content-Type: application/json' \
  --data '{"photos":[{"id":"photo_example","url":"/api/web-assets/properties/property_example/listing-photos/garden.jpg","description":"Front garden","group":"front yard"}]}'
```

Both calls return this shape (IDs and paths below are examples):

```json
{
  "photos": [
    {
      "id": "photo_example",
      "url": "/api/web-assets/properties/property_example/listing-photos/garden.jpg",
      "description": "Front garden",
      "group": "front yard"
    }
  ]
}
```

[Full response schema](/property-listing-photos.schema.json).
`photos` has 0–10 items in display order. `id` remains stable on reorder/edit;
`url` identifies uploaded bytes; `description` is empty if unset; `group` is null
if unset. No version field is added to the body. Responses are private/no-store
and include ETag. Empty photos clears the gallery and cover. Removing a photo
from this editor does not delete its original bytes or change the slideshow.

A stale If-Match returns 412; missing If-Match returns 428. Reload and reconcile
rather than overwriting someone else's changes. Invalid count, aspect ratio,
foreign paths or duplicates return 422; foreign photo IDs return 404. Unauthorized
requests return 401/403; concurrent property writes return 409; unavailable photo
validation or unconfirmed storage readback returns 503. Unexpected storage errors
can return 500 without publishing the staged gallery. An uncertain final save retains the write guard
until operator recovery verifies the original writer stopped; do not repeatedly
retry or bypass that guard. A GET can confirm which complete set is visible.

## Affiliate integration — existing routes, unchanged fields

```sh
curl --fail-with-body \
  'https://api-preview.wikiup.app/api/travel/listings?destination=julian-ca&includeImages=true' \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY"

curl --fail-with-body \
  'https://api-preview.wikiup.app/api/travel/listings/hotel%3Aproperty_example' \
  -H "Authorization: Bearer $WIKIUP_AFFILIATE_API_KEY"
```

Keep keys on the partner server. Catalog image fields and detail
`listing.coverImage`, `listing.gallery`, `listing.galleryGroups` retain their
existing schemas. Property-level images now come from this dedicated collection:
first photo as cover; `gallery` includes that cover and all remaining photos in saved order.
The catalog exposes only the cover; fetch listing detail for the full gallery.
Room detail photos remain room-specific; rental units use their own photos first
and the dedicated property collection as fallback. Approved listing access,
suspension, affiliate blacklists and booking attribution are unchanged.

Catalog `includeImages=false` remains lightweight and does not load the photo
collection. With images enabled, the catalog uses prepared thumbnails only;
detail may use the original while thumbnails are pending. Background processing
creates thumbnails without blocking owner saves. No photos means null cover and
an empty gallery; never substitute slideshow photos or fake inventory.

See [listing API guide](/travel-listings.md), [photo groups](/listing-gallery-groups.md)
and [public response schema](/travel-listings.schema.json) for all image fields,
responsive sizes and partial failures.

[Affiliate Integration Guide with cURL and populated image JSON](affiliate-integration-guide.md).
