Pagination

Les listes de l’API Sursa sont paginées par curseur : vous demandez au plus limit éléments, et la réponse vous indique comment obtenir la page suivante. Vous ne calculez jamais de décalage, et les éléments ne se répètent pas et ne disparaissent pas d’une page à l’autre quand les données changent entre-temps.

Une liste renvoie son curseur suivant de l’une de deux façons, selon la forme de sa réponse. La page de chaque point de terminaison dans la référence de l’API indique laquelle il utilise.

Listes avec enveloppe data

Les listes ajoutées pour l’API publique, comme le flux d’événements, renvoient un objet dont les éléments se trouvent dans 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
}

Quand has_more vaut true, demandez la page suivante en donnant à cursor la valeur de next_cursor, avec les mêmes filtres :

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

Les listes antérieures aux curseurs qui renvoient un objet conservent leur propre enveloppe (par exemple {"items": […], "total": 120}). Elles reçoivent next_cursor et has_more dans le même objet ; les éléments restent à leur place.

Listes qui renvoient un tableau

Quelques listes renvoient un tableau JSON nu, par exemple GET /v1/collections. La forme de leur réponse ne peut pas changer : la page suivante est donc indiquée dans les en-têtes :

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 avec rel="next" est l’adresse complète de la page suivante ; X-Next-Cursor est le même curseur, seul.
• L’absence de Link avec rel="next" et de X-Next-Cursor signifie qu’il s’agit de la dernière page.
• Sans limit, ces listes renvoient tous les éléments en une seule réponse, comme elles l’ont toujours fait. Passez limit pour les paginer ; le curseur mémorise la taille de page : la requête suivante peut donc omettre limit.
• GET /v1/cards fait exception : elle renvoie toujours des pages, 200 fiches par défaut et jusqu’à 1000 avec limit ; suivez donc X-Next-Cursor même sans 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;
  }
}

Le flux d’événements

Le flux d’événements GET /v1/webhook-events est un journal : sa pagination est donc un peu différente.

• Les événements sont classés par ordre croissant, du plus ancien au plus récent.
• next_cursor est renvoyé sur chaque page, même quand has_more vaut false. Conservez-le et interrogez de nouveau le flux plus tard avec le même curseur pour obtenir les événements survenus depuis. Le flux est une file que vous pouvez lire à votre rythme.
• Un événement apparaît dans le flux environ une seconde après la modification qu’il décrit, et jamais avant un événement déjà lu.
• Le flux contient les événements de toute l’organisation : sa lecture exige donc une clé dotée du rôle admin et de la portée webhooks:manage.

Exporter vers un entrepôt de données présente une boucle d’interrogation complète.

Règles des curseurs

• Un curseur est une chaîne opaque d’au plus 512 caractères. Ne l’analysez pas et ne le construisez pas vous-même : son format peut changer.
• Un curseur appartient à une liste et à un ensemble de filtres. Un curseur endommagé, issu d’une autre liste ou envoyé avec d’autres filtres renvoie 400 avec le code api.cursor_invalid.
• Chaque liste a un ordre de tri fixe qui se termine par une clé unique : chaque élément apparaît ainsi sur une seule page.
• Les listes ajoutées avec les curseurs ne renvoient pas de total ; les listes qui avaient déjà un total le conservent. Comptez les éléments au fur et à mesure si vous avez besoin d’un total.

Pagination par décalage

Certaines listes acceptaient offset avant l’arrivée des curseurs et l’acceptent toujours, pour que les intégrations existantes continuent de fonctionner. Dans le nouveau code, préférez cursor. offset et cursor ne peuvent pas être combinés : envoyer les deux renvoie 422 avec le code validation.failed.