Paginering

Lister i Sursas API pagineres med en cursor: Du ber om opptil limit elementer, og svaret forteller deg hvordan du får neste side. Du regner aldri ut offset, og elementer blir ikke gjentatt eller borte mellom sidene når dataene endres i mellomtiden.

En liste returnerer neste cursor på én av to måter, avhengig av formen på svaret. Siden for hver operasjon i API-referansen viser hvilken måte den bruker.

Lister med datakonvolutt

Lister som er lagt til for det offentlige API-et, for eksempel hendelsesfeeden, returnerer et objekt med elementene i data:

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
}

Når has_more er true, ber du om neste side med cursor satt til next_cursor og de samme filtrene:

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

Lister som fantes før cursorene og returnerer et objekt, beholder sin egen konvolutt (for eksempel {"items": […], "total": 120}). De får next_cursor og has_more i det samme objektet; elementene blir stående der de var.

Lister som returnerer et array

Noen få lister returnerer et rent JSON-array, for eksempel GET /v1/collections. Formen på svaret deres kan ikke endres, så neste side kommer i headere i stedet:

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 med rel="next" er den fullstendige adressen til neste side; X-Next-Cursor er den samme cursoren alene.
• Ingen Link med rel="next" og ingen X-Next-Cursor betyr at dette er siste side.
• Uten limit returnerer disse listene alle elementene i ett svar, slik de alltid har gjort. Send limit for å paginere dem; cursoren husker sidestørrelsen, så neste forespørsel kan utelate limit.
• GET /v1/cards er unntaket: Den returnerer alltid sider, 200 kort som standard og opptil 1000 med limit, så følg X-Next-Cursor også uten 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;
  }
}

Hendelsesfeeden

Hendelsesfeeden GET /v1/webhook-events er en logg, så den pagineres litt annerledes:

• Hendelsene kommer i stigende rekkefølge, eldste først.
• next_cursor returneres på hver side, også når has_more er false. Lagre den, og spør igjen senere med den samme cursoren for å få hendelsene som har skjedd siden. Feeden er en kø du kan lese i ditt eget tempo.
• En hendelse dukker opp i feeden innen omtrent ett sekund etter endringen den beskriver, og aldri før en hendelse som allerede er lest.
• Feeden inneholder hendelsene for hele organisasjonen, så for å lese den trenger du en nøkkel med rollen admin og scopet webhooks:manage.

Veiledningen Eksporter til et datavarehus viser en komplett pollingløkke.

Regler for cursorer

• En cursor er en ugjennomsiktig streng på opptil 512 tegn. Ikke tolk den eller bygg den selv: Formatet kan endres.
• En cursor hører til én liste og ett sett av filtre. En cursor som er skadet, kommer fra en annen liste eller sendes med andre filtre, returnerer 400 med koden api.cursor_invalid.
• Hver liste har en fast sorteringsrekkefølge som slutter med en unik nøkkel, så hvert element vises på nøyaktig én side.
• Lister som er lagt til med cursorer, returnerer ikke noe totalt antall; lister som hadde total fra før, beholder det. Tell elementene underveis hvis du trenger en total.

Paginering med offset

Noen lister godtok offset før cursorene ble innført, og gjør det fortsatt, slik at eksisterende integrasjoner fortsetter å virke. Foretrekk cursor i ny kode. offset og cursor kan ikke kombineres: Sender du begge, returneres 422 med koden validation.failed.