Pagination

Two schemes, and the endpoint decides which. It is not a preference you express per call.

Page-based — registers

Vendors, contracts, risk registers and risk scenarios take ?page= and ?limit= and return a pagination block:

curl "https://api.vendorica.com/v1/vendors?page=2&limit=50" \
  -H "Authorization: Bearer $VENDORICA_API_KEY"

{
  "success": true,
  "data": [ ],
  "pagination": { "page": 2, "limit": 50, "total": 118, "totalPages": 3 }
}

limit caps at 100. This is the right scheme when you want a page — a screen of results, a count, a jump to page 4.

Cursor-based — feeds

The audit log and the evidence feed are append-heavy: rows arrive while you are reading. Page 2 of an offset query, taken a minute after page 1, skips or repeats whatever landed in between — silently, so the gap looks like data that was never there. Those endpoints therefore take a cursor:

curl "https://api.vendorica.com/v1/audit-log?limit=100" \
  -H "Authorization: Bearer $VENDORICA_API_KEY"

{
  "success": true,
  "data": [ ],
  "cursor": { "nextCursor": "eyJ...", "hasMore": true, "limit": 100 }
}

Pass nextCursor back as ?cursor=, and stop when hasMore is false.

curl "https://api.vendorica.com/v1/audit-log?cursor=eyJ...&limit=100" \
  -H "Authorization: Bearer $VENDORICA_API_KEY"

Cursors are signed and opaque: do not parse, construct or mutate one. A tampered cursor and a malformed one both return 400 INVALID_CURSOR — the same answer on purpose, so the endpoint is not an oracle for what a valid cursor looks like.

Caution

?page= on a cursor endpoint is a 400, not a silent fallback. Accepting it would mean answering a walk-the-whole-collection request with a scheme that quietly drops rows. An explicit error is the one behaviour that cannot be mistaken for working.

Walking a whole collection

Cursor endpoints are safe to walk to the end. For page-based endpoints, walking every page of a register that is being edited underneath you has the same skip/repeat exposure — take the snapshot when writes are quiet, or reconcile on id rather than assuming the pages tile perfectly.

Pace the walk against RateLimit-Remaining rather than sleeping a fixed interval. See rate limits.