Publication and cache behavior
Source-reviewed draft; deployment and release verification pending.
Draft — source-reviewed on 22 October 2026. Publication state, deployed cache behavior and enabled capabilities have not been verified. No production API calls were made.
What a website response means
Public eligibility requires canonical property status PUBLISHED, a PUBLISHED publication for the site channel, and an active site channel. Another portal publication, catalog membership or a marketing flag does not satisfy those conditions. Public clients cannot override eligibility.
Search results additionally require a usable permitted public point inside the requested geometry. An eligible detail can therefore exist without appearing in map search. Neither search nor detail returns internal publication status or an availability calendar. Do not invent availability, published or booking-date fields in the API response.
For synthetic P9001, a 200 detail response means the current request passed the implemented eligibility checks. A later 404 can mean withdrawal, missing data, ineligibility or disabled capability. Present a safe unavailable state; the website cannot distinguish these private causes or recover the property through an internal route.
Cache controls and state transitions
Successful public JSON/media responses and handled errors within the public request boundary use Cache-Control: no-store. The outer application exception boundary returns {"detail":"Internal Server Error"} for unexpected 500 responses but may omit this header. The absence of the header on such a failure is not permission to cache public data. Do not build a static or offline mirror, service worker cache, persistent browser catalog or CDN cache that bypasses this policy. Search is POST and should not be treated as an indefinitely reusable URL resource.
Search returns items, total, page, page_size and total_pages; eligible membership, item values and selected thumbnails come from one database statement snapshot. That consistency applies to one request. Separate page requests do not promise the same snapshot, so a publication change can alter results between pages. Reset pagination when filters change and refresh current detail when a visitor opens a listing.
Optional fields may disappear when no longer populated or eligible. Treat omission and permitted nulls as unknown; clear previously rendered values instead of merging a new response over stale property facts. In particular, if agent or a contact channel disappears, hide the prior value. Do not keep an earlier address line when a new detail response no longer supplies it.
| Transition | Website behavior |
|---|---|
| Search refresh excludes a listing | Replace the current result set; avoid retaining the removed card as current. |
| Detail refresh returns 404 | Clear actionable property detail and show unavailable. |
| Gallery image becomes unavailable | Show an unavailable tile/placeholder; do not fetch its private original. |
| Public agent profile/contact disappears | Remove that public card/channel from the current render. |
| Request fails temporarily | Show a failure/retry state; do not label old data as current. |
This is UI state policy, not a new API event stream. No public publication event feed, tombstone endpoint or guaranteed polling interval is implemented. updated_at is a search filter, not even a returned property timestamp. It cannot discover withdrawals because withdrawn records are excluded. A future synchronization protocol requires a separately reviewed contract.
Media has its own eligibility checks
Property image requests re-check current property eligibility and asset binding. A request after committed withdrawal cannot use the property image endpoint to bypass that policy. Public agent photographs are different: an active user's enabled public profile and current owned, unretired photo control access; assignment to a currently published property is not required. Withdrawing P9001 alone does not revoke an otherwise eligible public agent photo.
Already delivered JSON or pixels cannot be remotely erased from a visitor's device. no-store and current endpoint checks constrain future delivery; do not promise global instantaneous revocation.
Loading, unavailable and recovery states
Keep initial loading, successful empty results, disabled/unavailable 404, invalid request 422, throttled 429 and temporary failure 503 distinct. For unexpected 500 or unreadable error bodies, show a generic failure with bounded retry; do not require a detail field or expose raw response text. Respect Retry-After; use bounded backoff and cancel/ignore obsolete requests. Disable actions that depend on a successful current response while it is unavailable. API and media source defaults are disabled, so environment handoff must confirm enablement before live integration; this draft does not change it.
Never expose internal status, private exact coordinates, investment values or notes in an error explanation. Safe user-facing copy is “This property is currently unavailable,” without guessing why. Optional public contact display is not permission to expose account-profile data.
Related operations
Current discovery: POST /api/v1/public/properties/search; current detail: GET /api/v1/public/properties/{public_id}; metadata: GET /api/v1/public/property-reference; property derivatives: GET /api/v1/public/properties/{public_id}/images/{asset_id}; independent public agent photos: GET /api/v1/public/agent-images/{asset_id}. See Publication, availability and privacy and Errors and pagination.
Updated 1 day ago