Paginación

Las listas de la API de Sursa se paginan con un cursor: usted pide hasta limit elementos y la respuesta le indica cómo obtener la página siguiente. Nunca calcula desplazamientos, y los elementos no se repiten ni se pierden entre páginas cuando los datos cambian mientras tanto.

Una lista devuelve su cursor siguiente de una de dos maneras, según la forma de su respuesta. La página de cada endpoint en la referencia de la API indica cuál usa.

Listas con envoltorio data

Las listas añadidas para la API pública, como el feed de eventos, devuelven un objeto con los elementos en 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
}

Cuando has_more es true, pida la página siguiente con cursor igual a next_cursor y los mismos filtros:

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

Las listas que ya existían antes de los cursores y devuelven un objeto conservan su propio envoltorio (por ejemplo, {"items": […], "total": 120}). Reciben next_cursor y has_more en el mismo objeto; los elementos se quedan donde estaban.

Listas que devuelven un array

Unas pocas listas devuelven un array JSON simple, por ejemplo GET /v1/collections. La forma de su respuesta no puede cambiar, así que la página siguiente llega en los encabezados:

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 con rel="next" es la dirección completa de la página siguiente; X-Next-Cursor es el mismo cursor por sí solo.
• Si no hay Link con rel="next" ni X-Next-Cursor, esta es la última página.
• Sin limit, estas listas devuelven todos los elementos en una sola respuesta, como siempre. Pase limit para paginarlas; el cursor recuerda el tamaño de página, así que la solicitud siguiente puede omitir limit.
• GET /v1/cards es la excepción: siempre devuelve páginas, de 200 tarjetas de forma predeterminada y de hasta 1000 con limit, así que siga X-Next-Cursor aunque no pase 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 feed de eventos

El feed de eventos GET /v1/webhook-events es un registro, así que se pagina de forma un poco distinta:

• Los eventos están en orden ascendente, del más antiguo al más reciente.
• next_cursor se devuelve en todas las páginas, incluso cuando has_more es false. Guárdelo y vuelva a preguntar más tarde con el mismo cursor para obtener los eventos ocurridos desde entonces. El feed es una cola que puede leer a su propio ritmo.
• Un evento aparece en el feed aproximadamente un segundo después del cambio que describe, y nunca antes de un evento que ya se ha leído.
• El feed contiene los eventos de toda la organización, por eso para leerlo hace falta una clave con el rol admin y el ámbito webhooks:manage.

Exportar a un almacén de datos muestra un bucle de sondeo completo.

Reglas de los cursores

• Un cursor es una cadena opaca de hasta 512 caracteres. No la analice ni la construya usted mismo: su formato puede cambiar.
• Un cursor pertenece a una lista y a un conjunto de filtros. Un cursor dañado, procedente de otra lista o enviado con otros filtros devuelve 400 con el código api.cursor_invalid.
• Cada lista tiene un orden fijo que termina con una clave única, de modo que cada elemento aparece exactamente en una página.
• Las listas añadidas con cursores no devuelven un recuento total; las listas que ya tenían total lo conservan. Si necesita un total, cuente los elementos a medida que avanza.

Paginación por desplazamiento

Algunas listas aceptaban offset antes de que se introdujeran los cursores, y lo siguen aceptando para que las integraciones existentes sigan funcionando. En el código nuevo, prefiera cursor. offset y cursor no se pueden combinar: enviar ambos devuelve 422 con el código validation.failed.