Paginierung

Listen der Sursa-API werden mit einem Cursor paginiert: Sie fordern bis zu limit Elemente an, und die Antwort sagt Ihnen, wie Sie die nächste Seite erhalten. Sie berechnen nie Offsets, und Elemente werden zwischen den Seiten weder doppelt geliefert noch ausgelassen, wenn sich die Daten zwischendurch ändern.

Eine Liste gibt ihren nächsten Cursor auf eine von zwei Arten zurück, je nach Form ihrer Antwort. Welche Art ein Endpunkt verwendet, zeigt seine Seite in der API-Referenz.

Listen mit Daten-Umschlag

Listen, die für die öffentliche API hinzugekommen sind, etwa der Ereignis-Feed, geben ein Objekt zurück, in dem die Elemente in data stehen:

curl "https://api.sursa.com/v1/webhook-events?limit=2" \
  -H "Authorization: Bearer $SURSA_API_KEY"

{
  "data": [
    {"id": "evt_8a1f…", "type": "card.published", "created_at": "2026-10-24T10:00:00Z"},
    {"id": "evt_8a20…", "type": "card.updated", "created_at": "2026-10-24T10:00:03Z"}
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbMTA0Ml19",
  "has_more": true
}

Ist has_more gleich true, fordern Sie die nächste Seite mit cursor gleich next_cursor und denselben Filtern an:

curl "https://api.sursa.com/v1/webhook-events?limit=2&cursor=eyJ2IjoxLCJrIjpbMTA0Ml19" \
  -H "Authorization: Bearer $SURSA_API_KEY"

Listen, die es schon vor den Cursorn gab und ein Objekt zurückgeben, behalten ihren eigenen Umschlag (zum Beispiel {"items": […], "total": 120}). Auch diese Listen erhalten next_cursor und has_more im selben Objekt; die Elemente bleiben, wo sie waren.

Listen, die ein Array zurückgeben

Einige wenige Listen geben ein reines JSON-Array zurück, zum Beispiel GET /v1/collections. Die Form ihrer Antwort kann sich nicht ändern, deshalb kommt die nächste Seite stattdessen in Headern:

curl -i "https://api.sursa.com/v1/collections?limit=50" \
  -H "Authorization: Bearer $SURSA_API_KEY"

HTTP/1.1 200 OK
Link: <https://api.example.com/v1/collections?limit=50&cursor=eyJ2IjoxLCJrIjpbNTBdfQ>; rel="next"
X-Next-Cursor: eyJ2IjoxLCJrIjpbNTBdfQ

[{"id": 1, "name": "support", …}, …]

• Link mit rel="next" ist die vollständige Adresse der nächsten Seite; X-Next-Cursor ist derselbe Cursor für sich allein.
• Fehlen Link mit rel="next" und X-Next-Cursor, ist dies die letzte Seite.
• Ohne limit geben diese Listen wie bisher alle Elemente in einer Antwort zurück. Übergeben Sie limit, um sie zu paginieren; der Cursor merkt sich die Seitengröße, sodass die nächste Anfrage limit weglassen kann.
• GET /v1/cards ist die Ausnahme: Diese Liste gibt immer Seiten zurück, standardmäßig 200 Karten und mit limit bis zu 1000. Folgen Sie X-Next-Cursor daher auch ohne limit.

// Every item of a list that returns an array.
async function* listArray(path) {
  let next = `https://api.sursa.com${path}?limit=200`;
  while (next) {
    const response = await fetch(next, { headers: { Authorization: `Bearer ${process.env.SURSA_API_KEY}` } });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    yield* await response.json();
    const cursor = response.headers.get("X-Next-Cursor");
    next = cursor ? `https://api.sursa.com${path}?cursor=${encodeURIComponent(cursor)}` : null;
  }
}

Der Ereignis-Feed

Der Ereignis-Feed GET /v1/webhook-events ist ein Protokoll und wird deshalb etwas anders paginiert:

• Ereignisse stehen in aufsteigender Reihenfolge, die ältesten zuerst.
• next_cursor wird auf jeder Seite zurückgegeben, auch wenn has_more gleich false ist. Speichern Sie ihn und fragen Sie später mit demselben Cursor erneut an, um die Ereignisse zu erhalten, die seitdem eingetreten sind. Der Feed ist eine Warteschlange, die Sie in Ihrem eigenen Tempo lesen.
• Ein Ereignis erscheint im Feed etwa eine Sekunde nach der Änderung, die es beschreibt, und nie vor einem Ereignis, das bereits gelesen wurde.
• Der Feed enthält die Ereignisse der ganzen Organisation, daher braucht das Lesen einen Schlüssel mit der Rolle admin und dem Scope webhooks:manage.

Export in ein Data Warehouse zeigt eine vollständige Abfrageschleife.

Regeln für Cursor

• Ein Cursor ist eine undurchsichtige Zeichenkette mit bis zu 512 Zeichen. Zerlegen oder bauen Sie ihn nicht selbst: Sein Format kann sich ändern.
• Ein Cursor gehört zu genau einer Liste und einer Kombination von Filtern. Ein Cursor, der beschädigt ist, aus einer anderen Liste stammt oder mit anderen Filtern gesendet wird, ergibt 400 mit dem Code api.cursor_invalid.
• Jede Liste hat eine feste Sortierung, die mit einem eindeutigen Schlüssel endet, sodass jedes Element auf genau einer Seite erscheint.
• Listen, die mit Cursorn hinzugekommen sind, geben keine Gesamtzahl zurück; Listen, die vorher ein total hatten, behalten es. Zählen Sie die Elemente beim Durchlaufen, wenn Sie eine Gesamtzahl brauchen.

Paginierung mit Offset

Einige Listen haben offset schon vor der Einführung der Cursor akzeptiert und tun das weiterhin, damit bestehende Integrationen funktionieren. Verwenden Sie in neuem Code bevorzugt cursor. offset und cursor lassen sich nicht kombinieren: Werden beide gesendet, ergibt das 422 mit dem Code validation.failed.