Pagination

When an endpoint returns many records, the response is a page rather than the full set. Paginated responses include an items array plus paging fields so you can walk through every row.

How it works

Pass limit and offset as query parameters:

The response body always includes:

{
  "items": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}

• items — the records for this page
• total — how many records match the query across all pages
• limit / offset — the values applied to this response (echoed from the request, after defaults and clamping)

Some list routes also accept search (and similar filters). Filtering changes which rows match; pagination still applies to that filtered set. See each endpoint for the exact query parameters.

Walking every page

1. Call the list endpoint with your filters. Start with offset=0 (or omit it).
2. Read items and total from the response.
3. If offset + limit < total, request the same path again with offset increased by limit.
4. Stop when offset + limit >= total, or when items is empty.

Example first page:

GET /api/v1/workspaces/acme/certificates?limit=50&offset=0

{
  "items": [{ "id": "…", "name": "Python Fundamentals" }],
  "total": 120,
  "limit": 50,
  "offset": 0
}

Next page:

GET /api/v1/workspaces/acme/certificates?limit=50&offset=50

Keep advancing offset by 50 until you have covered total (here 120).

Which endpoints paginate

List endpoints that return collections use this shape, including:

• List certificates
• List issues
• List recipients

Single-resource endpoints (for example get a certificate, or public verify) return one object and do not paginate.

Verifycate does not use cursor tokens (cursor, next, prev) on these routes. Always page with limit and offset.