> ## Documentation Index
> Fetch the complete documentation index at: https://api.housera.ro/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions and updates

> How the API evolves without breaking your integration, and what has changed in each version.

## 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](/en/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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.