Skip to main content

​
One live version

The API is released often, and every release is served under the same /v1 paths. Each release has a number such as 6.26.2. The current number is info.version in the OpenAPI document. You always call the latest release. There is no way to request an older one, except for the response formats described below.

​
What a release can change

Any release can add endpoints, optional parameters and response fields. Write your client to ignore fields it does not recognise. Changes that can break an existing integration are marked as breaking in the changelog, which lists customer-facing changes release by release. Check it when something you rely on behaves differently.

​
Formats you can choose with X-API-Version

Lists. These endpoints return a list in one of two formats:
  • property by location ID, by property ID, by source ID and by slug, and the property query;
  • listings by location, the listings query, the source query and the advanced query;
  • prosperity by code.
Without the header: { "success": true, "result": [...], "totalSize": 120, "size": 25 }. With X-API-Version: 2: { "object": "list", "url": "...", "data": [...], "has_more": true, "total_count": 120 }. Single listings. GET /v1/listings/{id} and GET /v1/listings/source/{provider}/{key} return { "success": true, "result": { ... } } without the header, and the listing itself, with "object": "listing", with X-API-Version: 2. Other endpoints have one format and ignore X-API-Version: 2. The TypeScript SDK sends X-API-Version: 2 on every request, so SDK calls always get the second format. Search suggest. Send the release you built against, such as X-API-Version: 2.150.0, and GET /v1/search/suggest answers in the format of that time: releases before 3.0.0 get the earlier format, 3.0.0 and later the current one. Without a release number, suggest uses your account’s default. The SDK always sends 2, which carries no release number, and replaces any value you set. See Search and autocomplete.

​
The TypeScript SDK

@vepler/sdk is generated from the API’s OpenAPI document and published to npm. Each SDK release takes the number of the API release it was generated from: SDK 6.8.0 was generated from API 6.8.0. The SDK is not republished for every API release, so an endpoint or field can reach the API before it reaches the SDK.

​
Data versions

Some datasets are versioned separately from API releases:
  • Heritage, Conservation and Land Constraint. GET /v1/{heritage|conservation|land-constraint}/snapshots lists the published snapshots, newest first. Pass snapshotId to a query to read one snapshot, so results stay the same while you page or while a newer snapshot is published.
  • Geography. GET /v1/geography/release returns the release the geography endpoints answer from: a named set of publisher vintages that fit together. Pass release, such as 2025.1, to the ancestors, descendants and children endpoints to pin one.