Пагінація

Списки 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 карток, а з limit — до 1000, тож переходьте за 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)

Деякі списки приймали offset ще до появи курсорів і приймають досі, щоб наявні інтеграції працювали далі. У новому коді віддавайте перевагу cursor. offset і cursor не можна поєднувати: якщо надіслати обидва, API поверне 422 з кодом validation.failed.