Skip to main content

​
Versioning

The version is part of the address: /api/v1. Within a version, the API evolves only compatibly:
  • fields are added, not renamed, not removed, and do not change type;
  • endpoints are added, existing ones retain their behavior;
  • codes never disappear: a changed code remains accepted and appears in retired from vocabulary, with its successor;
  • new values may appear in code lists (a subtype, a feature, a type of event).
For your integration to hold, ignore fields you do not recognize and handle an unknown code (for example, a new event type) without stopping. An incompatible change means a new version, /api/v2, which runs in parallel with /api/v1. The withdrawal of a version is announced at least 6 months in advance, on this page and through headers Deprecation and Sunset on responses from the old version.

​
1.0.0 — October 2026

The first public version of the write API. Your listings
  • Creation (POST /listings, with Idempotency-Key), validation without writing (POST /listings/validate), editing as JSON Merge Patch (PATCH /listings/{code}) and deletion (DELETE /listings/{code}).
  • Creation or updating by your id: PUT /listings/ref/{ref} and GET /account/listings/ref/{ref}.
  • Transitions: POST /listings/{code}/pause, /resume, /sold.
  • List and detail of your listings, in any state: GET /account/listings (with status, fields for reconciliation and cursor pagination) and GET /account/listings/{code}.
  • The versions of the listing with ETag and If-Match, with 412 on an old version.
  • Warnings warnings[] for fields and features that do not exist for type and transaction.
Photos
  • The complete list of photos, from URLs or direct uploads: PUT /listings/{code}/photos.
  • Direct upload via pre-signed URL: POST /uploads.
Events and webhooks
  • Signed webhooks according to the Webhooks Standard, configurable from Settings → API, with test, secret rotation, and delivery log.
  • Events listing.published, listing.rejected, listing.paused, listing.reactivated, listing.sold, listing.withdrawn, listing.edited_in_portal, media.failed, webhook.test.
  • Retrieval of events from the last 35 days: GET /events.
Errors, keys, and log
  • Errors in RFC 9457 format, with stable codes for each field.
  • Keys created from account, with rights (listings:read, listings:write, media:write), prefixes hsr_test_ and hsr_live_, and mandatory expiration.
  • API log in Settings → API → Log, with X-Request-Id on each response.
  • Sandbox on https://staging.housera.ro/api/v1.
Reading and vocabulary
  • Public catalog of active listings: GET /listings and GET /listings/{code}.
  • Public vocabulary, with the type and unit of each field: GET /schema.