Stránkování

Seznamy Sursa API se stránkují pomocí kurzoru: požádáte nejvýše o limit položek a odpověď vám sdělí, jak získat další stránku. Posuny nikdy nepočítáte a položky se mezi stránkami neopakují ani neztrácejí, ani když se data mezitím změní.

Seznam vrací další kurzor jedním ze dvou způsobů podle tvaru své odpovědi. Stránka každé operace v referenci API ukazuje, který z nich používá.

Seznamy s obálkou data

Seznamy přidané pro veřejné API, například kanál událostí, vracejí objekt s položkami v 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
}

Když je has_more rovno true, vyžádejte si další stránku s cursor nastaveným na next_cursor a se stejnými filtry:

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

Seznamy, které existovaly před zavedením kurzorů a vracejí objekt, si ponechávají vlastní obálku (například {"items": […], "total": 120}). next_cursor a has_more dostávají ve stejném objektu; položky zůstávají tam, kde byly.

Seznamy, které vracejí pole

Několik seznamů vrací holé pole JSON, například GET /v1/collections. Tvar jejich odpovědi se nemůže změnit, proto další stránka přichází v hlavičkách:

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 s rel="next" je úplná adresa další stránky; X-Next-Cursor je tentýž kurzor samostatně.
• Pokud chybí Link s rel="next" i X-Next-Cursor, jde o poslední stránku.
• Bez limit vracejí tyto seznamy všechny položky v jedné odpovědi, jako vždy. Chcete-li je stránkovat, předejte limit; kurzor si velikost stránky pamatuje, takže další požadavek může limit vynechat.
• GET /v1/cards je výjimka: stránky vrací vždy, ve výchozím stavu po 200 kartách a s limit až po 1000, proto sledujte X-Next-Cursor i bez 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;
  }
}

Kanál událostí

Kanál událostí GET /v1/webhook-events je protokol, a proto se stránkuje trochu jinak:

• Události jsou ve vzestupném pořadí, nejstarší první.
• next_cursor se vrací na každé stránce, i když je has_more rovno false. Uložte si ho a později se zeptejte znovu se stejným kurzorem – dostanete události, které mezitím nastaly. Kanál je fronta, kterou můžete číst vlastním tempem.
• Událost se v kanálu objeví zhruba do sekundy od změny, kterou popisuje, a nikdy před událostí, která už byla přečtena.
• Kanál obsahuje události celé organizace, proto jeho čtení vyžaduje klíč s rolí admin a rozsahem webhooks:manage.

Export do datového skladu ukazuje úplnou smyčku dotazování.

Pravidla pro kurzory

• Kurzor je neprůhledný řetězec o délce až 512 znaků. Neparsujte ho ani ho nesestavujte vlastním kódem: jeho formát se může změnit.
• Kurzor patří k jednomu seznamu a jedné sadě filtrů. Poškozený kurzor, kurzor z jiného seznamu nebo kurzor odeslaný s jinými filtry vrátí 400 s kódem api.cursor_invalid.
• Každý seznam má pevné pořadí řazení zakončené jedinečným klíčem, takže se každá položka objeví právě na jedné stránce.
• Seznamy přidané spolu s kurzory nevracejí celkový počet; seznamy, které total měly už dřív, si ho ponechávají. Pokud celkový počet potřebujete, počítejte položky průběžně.

Stránkování posunem (offset)

Některé seznamy přijímaly offset už před zavedením kurzorů a přijímají ho dál, aby stávající integrace fungovaly i nadále. V novém kódu dávejte přednost cursor. offset a cursor nelze kombinovat: odeslání obou vrátí 422 s kódem validation.failed.