Странициране

Списъците на Sursa API се разделят на страници с курсор: искате до limit елемента, а отговорът ви казва как да получите следващата страница. Никога не изчислявате отмествания и елементите не се повтарят и не изчезват между страниците, когато данните междувременно се променят.

Списъкът връща следващия си курсор по един от два начина в зависимост от вида на отговора си. Страницата на всяка операция в справочника на API показва кой от тях се използва.

Списъци с обвивка data

Списъците, добавени за публичния API, например лентата със събития, връщат обект с елементите в 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
}

Когато has_more е true, поискайте следващата страница с cursor, равен на next_cursor, и със същите филтри:

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

Списъците, които са съществували преди курсорите и връщат обект, запазват собствената си обвивка (например {"items": […], "total": 120}). Те получават next_cursor и has_more в същия обект; елементите остават там, където са били.

Списъци, които връщат масив

Няколко списъка връщат чист JSON масив, например GET /v1/collections. Видът на отговора им не може да се промени, затова следващата страница идва в заглавки:

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 с rel="next" е пълният адрес на следващата страница; X-Next-Cursor е същият курсор самостоятелно.
• Липсата на Link с rel="next" и на X-Next-Cursor означава, че това е последната страница.
• Без limit тези списъци връщат всички елементи в един отговор, както винаги досега. Подайте limit, за да ги разделите на страници; курсорът помни размера на страницата, затова следващата заявка може да пропусне limit.
• GET /v1/cards е изключението: той винаги връща страници, по подразбиране по 200 карти и до 1000 с limit, затова следвайте X-Next-Cursor дори без 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;
  }
}

Лентата със събития

Лентата със събития GET /v1/webhook-events е дневник, затова се разделя на страници малко по-различно:

• Събитията са във възходящ ред, най-старите първи.
• next_cursor се връща на всяка страница, дори когато has_more е false. Запазете го и попитайте отново по-късно със същия курсор, за да получите събитията, случили се междувременно. Лентата е опашка, която може да четете със свое темпо.
• Събитието се появява в лентата около секунда след промяната, която описва, и никога преди събитие, което вече е прочетено.
• Лентата съдържа събитията на цялата организация, затова за четенето ѝ е нужен ключ с ролята admin и обхвата webhooks:manage.

Експорт в хранилище за данни показва цялостен цикъл на периодична проверка.

Правила за курсорите

• Курсорът е непрозрачен низ до 512 знака. Не го анализирайте и не го съставяйте сами: форматът му може да се промени.
• Курсорът принадлежи на един списък и на един набор от филтри. Курсор, който е повреден, идва от друг списък или е изпратен с други филтри, връща 400 с кода api.cursor_invalid.
• Всеки списък има фиксиран ред на сортиране, който завършва с уникален ключ, затова всеки елемент се появява точно на една страница.
• Списъците, добавени заедно с курсорите, не връщат общ брой; списъците, които са имали total и преди, го запазват. Ако ви трябва общ брой, бройте елементите в движение.

Странициране с отместване

Някои списъци приемаха offset, преди да бъдат въведени курсорите, и все още го приемат, за да продължат да работят съществуващите интеграции. В новия код предпочитайте cursor. offset и cursor не може да се комбинират: изпращането на двата връща 422 с кода validation.failed.