# REST-API: Blättern

Adresse: https://docs.athaus.ai/api/v1/blaettern

> 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.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-16

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 [#inserate-nextpagetoken]

`GET /v1/listings` liefert die Ids der Inserate, zuletzt angelegte zuerst, und eine zusätzliche Zusammenfassung derselben Inserate.

```bash
curl "https://api.athaus.ai/v1/listings?limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "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:

```bash
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 [#andere-ressourcen-cursor]

Kontakte, Anfragen, Besichtigungen, Dateien, Vorschläge, Ereignisse und Webhook-Endpunkte liefern ein Listenobjekt.

```bash
curl "https://api.athaus.ai/v1/contacts?limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "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](/api/v1/referenz). Ereignisse haben kein `sort` und kein `updatedSince`: siehe [Ereignisse](/api/v1/ereignisse).

## Änderungen verfolgen [#änderungen-verfolgen]

Willst du nur wissen, was sich seit deinem letzten Abruf geändert hat, schicke den Zeitpunkt deines letzten Abrufs als `updatedSince`:

```bash
curl "https://api.athaus.ai/v1/contacts?sort=updatedAt&updatedSince=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer ath_live_..."
```

## Das solltest du wissen [#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.
