Skip to main content
Novi Kvadrat Developers
On this page

Photos and the fetcher

Send HTTPS photo URLs; our fetcher downloads, checks and re-encodes them. The rules, the caps, reuse by digest, and what happens when a fetch fails.

There is no upload endpoint. photos[] holds HTTPS URLs; our fetcher downloads each image when the item is imported.

The rules#

  • 0 to 64 photos in the payload. The first is the cover; the order you send is the order we show.
  • Each url is a public https:// URL: no IP address, no local host name, no port other than 443, no credentials, up to 2,048 characters. A URL listed twice is duplicate_photo_url.
  • room_type is optional: exterior, living_room, kitchen, bedroom, bathroom, balcony, hallway, view, garage, other.
  • caption is optional, up to 500 characters.

How many we keep#

  • The agency's plan caps the photos stored. Extra photos are dropped from the end, and the item carries the warning photo_cap_applied.
  • At least 3 photos are needed to publish. An active item that ends with fewer than 3 stored photos fails with photo_minimum. A listing that is already published keeps its previous photo set in that case, so it never goes live with too few. A 2-photo listing can still be staged as inactive.
  • Sandbox items fetch at most 8 photos (nothing is stored on the sandbox).

Reuse: unchanged photos are not fetched again#

We keep each photo's source URL and the SHA-256 of the bytes we fetched. On the next push:

  • with your digest (the SHA-256 of the image bytes, 64 lower-case hex characters), a photo is reused only when its URL matches a stored photo and your digest equals the SHA-256 of the bytes we stored for it; otherwise it is downloaded again — change the digest when the image at a URL changes;
  • without your digest, the URL alone decides. Without your digest, a URL we already hold is reused as is and never fetched again.

If you replace the image behind a URL without changing the URL, send digest so we notice.

When a fetch fails#

Failure Examples What happens
Transient timeout, HTTP 5xx or 429 from your host the item retries with backoff (1, 2, 5, 15, 30 minutes); after 5 attempts it fails with photo_fetch_failed
Permanent HTTP 4xx, not an image, too large, a disallowed address the item fails at once with photo_fetch_failed; the URL and the reason are in the item's details

A failed item does not change what is already published. Fix the photo and push again.

Fetcher limits#

HTTPS on port 443 only, public hosts only, at most 3 redirects, 15 seconds and 10 MiB per image, JPEG, PNG, WebP or AVIF (SVG and GIF are refused). Images are re-encoded to WebP, at most 2560 px, metadata stripped. Our egress addresses are not published: serve photos from a public CDN. Details on the fetcher page.

Last updated