REST API: pagination
Every list of /v1 returns one page and a way to the next. Listings use a page token, the other resources a cursor. No total count.
Last updated:
Every list of /v1 comes in pages. You fetch the first page and send the token from the response with the next request, until there is no further page. Listings follow OpenImmo and page with a page token. The other resources page with a cursor.
Listings: nextPageToken
GET /v1/listings returns the ids of the listings, most recently created first, and an additive summary of the same listings.
curl "https://api.athaus.ai/v1/listings?limit=2" \
-H "Authorization: Bearer ath_live_..."{
"externalListingIds": ["WE-12", "WE-14"],
"nextPageToken": "eyJzIjoiMjAyNi0xMS0xMVQwOTozMDowMFoifQ",
"listings": [
{
"listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
"externalListingId": "WE-12",
"status": "active",
"updatedAt": "2026-11-11T09:30:00Z"
},
{
"listingId": "0190f39e-52a0-7d13-b6c4-8e1f0a9d7c25",
"externalListingId": "WE-14",
"status": "draft",
"updatedAt": "2026-11-10T16:02:41Z"
}
]
}The next page:
curl "https://api.athaus.ai/v1/listings?limit=2&nextPageToken=eyJzIjoiMjAyNi0xMS0xMVQwOTozMDowMFoifQ" \
-H "Authorization: Bearer ath_live_..."On the last page nextPageToken is null.
| Parameter | Effect |
|---|---|
limit | entries per page, 1 to 100, default 50. More than 100 is a 400, it is never silently capped |
nextPageToken | the value from the previous page |
updatedSince | only listings changed since this instant (ISO 8601) |
status | draft, active, paused, reserved or closed |
distributionType, city, postalcode | filters on the listing |
Other resources: cursor
Contacts, inquiries, viewings, files, proposals, events and webhook endpoints return a list object.
curl "https://api.athaus.ai/v1/contacts?limit=2" \
-H "Authorization: Bearer ath_live_..."{
"object": "list",
"data": [
{ "object": "contact", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" },
{ "object": "contact", "id": "0190f39e-52a0-7d13-b6c4-8e1f0a9d7c25" }
],
"hasMore": true,
"nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIs..."
}data is cut to the id here, every object has all its fields. Send nextCursor as cursor to get the next page. On the last page hasMore is false and nextCursor is null.
| Parameter | Effect |
|---|---|
limit | entries per page, 1 to 100, default 50 |
cursor | the value from nextCursor of the previous page |
updatedSince | only objects changed since this instant (ISO 8601) |
sort | createdAt, -createdAt (default), updatedAt or -updatedAt. The minus sorts descending |
Filters such as city or status are on the page of the operation in the reference. Events have no sort and no updatedSince: see Events.
Follow changes
If you only want to know what changed since your last fetch, send the instant of your last fetch as updatedSince:
curl "https://api.athaus.ai/v1/contacts?sort=updatedAt&updatedSince=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer ath_live_..."What you should know
- There is no total count. It would cost a second query over the whole stock on every page. Read until the last page.
- A token and a cursor are opaque. Send them back unchanged, do not take them apart. Their content may change without that being a break.
- A cursor belongs to its sort order. If you change
sortin the middle of paging, the API answers400withinvalid_query. Start again with the first page. - There is no offset. An offset shifts as soon as somebody creates something between two fetches.
Keep reading
REST API: the first call
The REST API reads and writes the listings, contacts, inquiries, viewings and files of your office. One key, one call, JSON back.
REST API: listings in the OpenImmo 2.0 shape
Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.
REST API reference
Every operation of /v1 with parameters, response and example, generated from the contract of the API.