Pagination

List endpoints in the Dentally NexGen API are cursor‑paginated. A cursor is an opaque token that points to the next page of results; you carry it forward from one response to the next request until the server tells you there are no more pages.

Cursor pagination scales predictably for large datasets and is stable under inserts and deletes happening between page fetches — unlike offset pagination, which can skip or repeat rows when the underlying data changes.

Paginated responses always include a meta object alongside data:

{
  "data": [ /* … */ ],
  "meta": {
    "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wOC0xMlQxMTowMDowMFoifQ"
  }
}

meta.cursor is:

• A string when there is at least one more page. Pass it back as the cursor query parameter on the next request.
• null when you have reached the last page. Stop iterating.

Treat the cursor as opaque — its contents are an implementation detail and may change without notice.

# First page
curl 'https://…/v2/sites?limit=50' \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Dentally-API-Version: 2026-01-01' \
  -H 'X-Practice-Id: <practice-uuid>'

# Subsequent pages — pass meta.cursor from the previous response
curl 'https://…/v2/sites?limit=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wOC0xMlQxMTowMDowMFoifQ' \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Dentally-API-Version: 2026-01-01' \
  -H 'X-Practice-Id: <practice-uuid>'

• Choose the largest limit your client can comfortably process. Fewer round trips means faster end‑to‑end iteration.
• Iterate to completion in a tight loop; cursors are not designed to be held for long periods.
• Don't try to construct, mutate or compare cursors. They are not URLs and carry no guarantees about their internal shape.