REST-API: Blättern
Jede Liste von /v1 liefert eine Seite und einen Weg zur nächsten. Inserate nutzen ein Page Token, die übrigen Ressourcen einen Cursor. Keine Gesamtzahl.
Zuletzt aktualisiert:
Jede Liste von /v1 kommt in Seiten. Du holst die erste Seite und schickst das Token aus der Antwort mit der nächsten Anfrage mit, bis es keine weitere Seite gibt. Inserate folgen OpenImmo und blättern mit einem Page Token. Die übrigen Ressourcen blättern mit einem Cursor.
Inserate: nextPageToken
GET /v1/listings liefert die Ids der Inserate, zuletzt angelegte zuerst, und eine zusätzliche Zusammenfassung derselben Inserate.
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"
}
]
}Die nächste Seite:
curl "https://api.athaus.ai/v1/listings?limit=2&nextPageToken=eyJzIjoiMjAyNi0xMS0xMVQwOTozMDowMFoifQ" \
-H "Authorization: Bearer ath_live_..."Auf der letzten Seite ist nextPageToken null.
| Parameter | Wirkung |
|---|---|
limit | Einträge je Seite, 1 bis 100, Vorgabe 50. Mehr als 100 ist ein 400, es wird nie stillschweigend gekappt |
nextPageToken | der Wert von der vorigen Seite |
updatedSince | nur Inserate, die seit diesem Zeitpunkt geändert wurden (ISO 8601) |
status | draft, active, paused, reserved oder closed |
distributionType, city, postalcode | Filter auf das Inserat |
Andere Ressourcen: Cursor
Kontakte, Anfragen, Besichtigungen, Dateien, Vorschläge, Ereignisse und Webhook-Endpunkte liefern ein Listenobjekt.
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 ist hier auf die id gekürzt, jedes Objekt hat alle seine Felder. Schicke nextCursor als cursor, um die nächste Seite zu holen. Auf der letzten Seite ist hasMore false und nextCursor null.
| Parameter | Wirkung |
|---|---|
limit | Einträge je Seite, 1 bis 100, Vorgabe 50 |
cursor | der Wert aus nextCursor der vorigen Seite |
updatedSince | nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601) |
sort | createdAt, -createdAt (Vorgabe), updatedAt oder -updatedAt. Das Minus sortiert absteigend |
Filter wie city oder status stehen auf der Seite der Operation in der Referenz. Ereignisse haben kein sort und kein updatedSince: siehe Ereignisse.
Änderungen verfolgen
Willst du nur wissen, was sich seit deinem letzten Abruf geändert hat, schicke den Zeitpunkt deines letzten Abrufs als updatedSince:
curl "https://api.athaus.ai/v1/contacts?sort=updatedAt&updatedSince=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer ath_live_..."Das solltest du wissen
- Es gibt keine Gesamtzahl. Sie würde bei jeder Seite eine zweite Abfrage über den ganzen Bestand kosten. Lies bis zur letzten Seite.
- Token und Cursor sind undurchsichtig. Schick sie unverändert zurück und nimm sie nicht auseinander. Ihr Inhalt kann sich ändern, ohne dass das ein Bruch ist.
- Ein Cursor gehört zu seiner Sortierung. Wechselst du mitten im Blättern
sort, antwortet die API mit400undinvalid_query. Fang mit der ersten Seite neu an. - Es gibt kein Offset. Ein Offset verschiebt sich, sobald jemand zwischen zwei Abrufen etwas anlegt.
Weiter lesen
REST-API: der erste Aufruf
Die REST-API liest und schreibt Inserate, Kontakte, Anfragen, Besichtigungen und Dateien deines Büros. Ein Key, ein Aufruf, JSON zurück.
REST-API: Inserate in der Form von OpenImmo 2.0
Inserate lesen und schreiben in der Form von OpenImmo 2.0. Zwei Ids, Entwürfe, Quittungen, Hinweise und jedes Mitglied eines Inserats.
REST-API Referenz
Jede Operation von /v1 mit Parametern, Antwort und Beispiel, aus dem Vertrag der API erzeugt.