分页

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", …}, …]

• 带有 rel="next" 的 Link 是下一页的完整地址；X-Next-Cursor 单独给出同一个游标。
• 没有带 rel="next" 的 Link，也没有 X-Next-Cursor，表示这是最后一页。
• 不带 limit 时，这些列表与以往一样，在一个响应中返回所有项。传入 limit 即可分页；游标会记住每页数量，因此下一个请求可以不传 limit。
• GET /v1/cards 是例外：它总是分页返回，默认每页 200 张卡片，用 limit 最多可设为 1000，因此即使不传 limit，也要跟随 X-Next-Cursor 读取下一页。

// 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。