Sidindelning

Listorna i Sursa API delas in i sidor med en markör: du ber om upp till limit element, och svaret talar om hur du får nästa sida. Du beräknar aldrig förskjutningar, och element upprepas inte och försvinner inte mellan sidorna när data ändras under tiden.

En lista returnerar sin nästa markör på ett av två sätt, beroende på hur svaret är uppbyggt. Sidan för varje slutpunkt i API-referensen visar vilket sätt den använder.

Listor med data-kuvert

Listor som har lagts till för det offentliga API:et, till exempel händelseflödet, returnerar ett objekt med elementen i 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
}

När has_more är true begär du nästa sida med cursor satt till next_cursor och samma filter:

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

Listor som fanns innan markörerna och returnerar ett objekt behåller sitt eget kuvert (till exempel {"items": […], "total": 120}). De får next_cursor och has_more i samma objekt; elementen ligger kvar där de var.

Listor som returnerar en array

Några listor returnerar en ren JSON-array, till exempel GET /v1/collections. Formen på deras svar kan inte ändras, så nästa sida kommer i stället i huvuden:

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 med rel="next" är den fullständiga adressen till nästa sida; X-Next-Cursor är samma markör för sig.
• Inget Link med rel="next" och inget X-Next-Cursor betyder att det här är den sista sidan.
• Utan limit returnerar de här listorna alla element i ett enda svar, som de alltid har gjort. Skicka limit för att dela in dem i sidor; markören kommer ihåg sidstorleken, så nästa anrop kan utelämna limit.
• GET /v1/cards är undantaget: den returnerar alltid sidor, 200 kort som standard och upp till 1000 med limit, så följ X-Next-Cursor även utan 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;
  }
}

Händelseflödet

Händelseflödet GET /v1/webhook-events är en logg, så sidindelningen fungerar lite annorlunda:

• Händelserna kommer i stigande ordning, de äldsta först.
• next_cursor returneras på varje sida, även när has_more är false. Spara den och fråga igen senare med samma markör för att få de händelser som har inträffat sedan dess. Flödet är en kö som du kan läsa i din egen takt.
• En händelse dyker upp i flödet inom ungefär en sekund efter ändringen som den beskriver, och aldrig före en händelse som redan har lästs.
• Flödet innehåller händelserna för hela organisationen, så för att läsa det behövs en nyckel med rollen admin och omfånget webhooks:manage.

Export till ett datalager visar en komplett pollningsloop.

Regler för markörer

• En markör är en ogenomskinlig sträng på upp till 512 tecken. Tolka den inte och bygg den inte själv: dess format kan ändras.
• En markör hör till en lista och en uppsättning filter. En markör som är skadad, kommer från en annan lista eller skickas med andra filter returnerar 400 med koden api.cursor_invalid.
• Varje lista har en fast sorteringsordning som slutar med en unik nyckel, så varje element förekommer på exakt en sida.
• Listor som har lagts till med markörer returnerar inget totalt antal; listor som hade total tidigare behåller det. Räkna elementen medan du läser om du behöver en summa.

Sidindelning med offset

Vissa listor tog emot offset innan markörerna infördes, och gör det fortfarande, så att befintliga integrationer fortsätter att fungera. Använd hellre cursor i ny kod. offset och cursor kan inte kombineras: skickar du båda returneras 422 med koden validation.failed.