Paginació

Les llistes de l’API de Sursa es paginen amb un cursor: demaneu fins a limit elements i la resposta us indica com obtenir la pàgina següent. No cal calcular mai desplaçaments, i els elements no es repeteixen ni es perden entre pàgines quan les dades canvien mentrestant.

Una llista retorna el cursor següent d’una de dues maneres, segons la forma de la resposta. La pàgina de cada punt final a la referència de l’API mostra quina fa servir.

Llistes amb embolcall data

Les llistes afegides per a l’API pública, com ara el canal d’esdeveniments, retornen un objecte amb els elements a 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
}

Quan has_more és true, demaneu la pàgina següent amb cursor igual a next_cursor i els mateixos filtres:

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

Les llistes que existien abans dels cursors i retornen un objecte mantenen el seu propi embolcall (per exemple, {"items": […], "total": 120}). Reben next_cursor i has_more al mateix objecte; els elements es queden on eren.

Llistes que retornen una matriu

Unes quantes llistes retornen una matriu JSON simple, per exemple GET /v1/collections. La forma de la seva resposta no pot canviar, per això la pàgina següent arriba a les capçaleres:

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 amb rel="next" és l’adreça completa de la pàgina següent; X-Next-Cursor és el mateix cursor sol.
• Si no hi ha cap Link amb rel="next" ni cap X-Next-Cursor, aquesta és l’última pàgina.
• Sense limit, aquestes llistes retornen tots els elements en una sola resposta, com han fet sempre. Passeu limit per paginar-les; el cursor recorda la mida de pàgina, de manera que la sol·licitud següent pot ometre limit.
• GET /v1/cards és l’excepció: sempre retorna pàgines, 200 entrades per defecte i fins a 1000 amb limit, de manera que seguiu X-Next-Cursor fins i tot sense 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;
  }
}

El canal d’esdeveniments

El canal d’esdeveniments GET /v1/webhook-events és un registre, per això es pagina d’una manera una mica diferent:

• Els esdeveniments van en ordre ascendent, primer els més antics.
• next_cursor es retorna a cada pàgina, fins i tot quan has_more és false. Deseu-lo i torneu a demanar més tard amb el mateix cursor per obtenir els esdeveniments que s’han produït des d’aleshores. El canal és una cua que podeu llegir al vostre ritme.
• Un esdeveniment apareix al canal aproximadament un segon després del canvi que descriu, i mai abans d’un esdeveniment que ja s’ha llegit.
• El canal conté els esdeveniments de tota l’organització, de manera que per llegir-lo cal una clau amb el rol admin i l’àmbit webhooks:manage.

La guia Exportar a un magatzem de dades mostra un bucle de sondeig complet.

Regles dels cursors

• Un cursor és una cadena opaca de fins a 512 caràcters. No l’analitzeu ni el construïu pel vostre compte: el seu format pot canviar.
• Un cursor pertany a una llista i a un conjunt de filtres. Un cursor malmès, que prové d’una altra llista o que s’envia amb filtres diferents retorna 400 amb el codi api.cursor_invalid.
• Cada llista té un ordre fix que acaba amb una clau única, de manera que cada element apareix exactament en una pàgina.
• Les llistes afegides amb cursors no retornen un recompte total; les llistes que ja tenien un total el mantenen. Si necessiteu un total, compteu els elements a mesura que avanceu.

Paginació per desplaçament

Algunes llistes acceptaven offset abans que s’introduïssin els cursors, i encara l’accepten, perquè les integracions existents continuïn funcionant. Al codi nou, feu servir preferentment cursor. offset i cursor no es poden combinar: si envieu tots dos, es retorna 422 amb el codi validation.failed.