AthausDoku

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.

ParameterWirkung
limitEinträge je Seite, 1 bis 100, Vorgabe 50. Mehr als 100 ist ein 400, es wird nie stillschweigend gekappt
nextPageTokender Wert von der vorigen Seite
updatedSincenur Inserate, die seit diesem Zeitpunkt geändert wurden (ISO 8601)
statusdraft, active, paused, reserved oder closed
distributionType, city, postalcodeFilter 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.

ParameterWirkung
limitEinträge je Seite, 1 bis 100, Vorgabe 50
cursorder Wert aus nextCursor der vorigen Seite
updatedSincenur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601)
sortcreatedAt, -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 mit 400 und invalid_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

Auf dieser Seite