Paginering

Lijsten van de Sursa API worden gepagineerd met een cursor: je vraagt maximaal limit items op, en de response vertelt je hoe je de volgende pagina krijgt. Je rekent nooit offsets uit, en items worden tussen pagina’s niet herhaald en raken niet zoek als de gegevens in de tussentijd veranderen.

Een lijst geeft zijn volgende cursor op een van twee manieren terug, afhankelijk van de vorm van zijn response. Op de pagina van elk endpoint in de API-referentie staat welke manier het gebruikt.

Lijsten met een data-envelop

Lijsten die voor de openbare API zijn toegevoegd, zoals de eventfeed, geven een object terug met de items in 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
}

Is has_more gelijk aan true, vraag dan de volgende pagina op met cursor ingesteld op next_cursor en dezelfde filters:

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

Lijsten die al vóór de cursors bestonden en een object teruggeven, houden hun eigen envelop (bijvoorbeeld {"items": […], "total": 120}). Ze krijgen next_cursor en has_more in hetzelfde object; de items blijven waar ze stonden.

Lijsten die een array teruggeven

Een paar lijsten geven een kale JSON-array terug, bijvoorbeeld GET /v1/collections. De vorm van hun response kan niet veranderen, dus de volgende pagina komt in plaats daarvan in headers:

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 met rel="next" is het volledige adres van de volgende pagina; X-Next-Cursor is dezelfde cursor op zichzelf.
• Geen Link met rel="next" en geen X-Next-Cursor betekent dat dit de laatste pagina is.
• Zonder limit geven deze lijsten alle items in één response terug, zoals altijd. Geef limit mee om ze te pagineren; de cursor onthoudt de paginagrootte, dus het volgende request mag limit weglaten.
• GET /v1/cards is de uitzondering: die geeft altijd pagina’s terug, standaard 200 kaarten en met limit maximaal 1000, dus volg X-Next-Cursor ook zonder 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;
  }
}

De eventfeed

De eventfeed GET /v1/webhook-events is een log en pagineert daarom iets anders:

• Events staan in oplopende volgorde, de oudste eerst.
• next_cursor wordt op elke pagina teruggegeven, ook als has_more gelijk is aan false. Bewaar hem en vraag later opnieuw met dezelfde cursor om de events te krijgen die sindsdien zijn gebeurd. De feed is een wachtrij die je in je eigen tempo kunt lezen.
• Een event verschijnt in de feed binnen ongeveer een seconde na de wijziging die het beschrijft, en nooit vóór een event dat al is gelezen.
• De feed bevat de events van de hele organisatie, dus om hem te lezen heb je een sleutel nodig met de rol admin en de scope webhooks:manage.

Export naar een datawarehouse laat een volledige pollinglus zien.

Regels voor cursors

• Een cursor is een ondoorzichtige string van maximaal 512 tekens. Parseer hem niet en stel hem niet zelf samen: het formaat kan veranderen.
• Een cursor hoort bij één lijst en één set filters. Een cursor die beschadigd is, uit een andere lijst komt of met andere filters wordt meegestuurd, geeft 400 met de code api.cursor_invalid.
• Elke lijst heeft een vaste sorteervolgorde die eindigt op een unieke sleutel, zodat elk item op precies één pagina verschijnt.
• Lijsten die met cursors zijn toegevoegd, geven geen totaal aantal terug; lijsten die al een total hadden, houden het. Tel de items onderweg als je een totaal nodig hebt.

Paginering met offset

Sommige lijsten accepteerden offset al voordat er cursors waren, en doen dat nog steeds, zodat bestaande integraties blijven werken. Gebruik in nieuwe code bij voorkeur cursor. offset en cursor kunnen niet samen worden gebruikt: beide meesturen geeft 422 met de code validation.failed.