Пагинација

Листе у API интерфејсу платформе Sursa деле се на странице помоћу курсора: тражите до limit ставки, а одговор вам каже како да добијете следећу страницу. Никада не рачунате помаке, а ставке се између страница не понављају и не нестају када се подаци у међувремену промене.

Параметар	Вредност
`limit`	Колико ставки по страници, обично од 1 до 200. Нове листе подразумевано враћају 50; референца приказује распон и подразумевану вредност сваке листе.
`cursor`	Курсор са претходне странице. За прву страницу га изоставите.

Листа враћа следећи курсор на један од два начина, зависно од облика свог одговора. Страница сваке операције у 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 не могу да се комбинују: слање оба параметра враћа 422 са кодом validation.failed.