General

Pagination

Every collection pages the same way: an opaque cursor, never an offset.

curl "https://api.veruapis.com/v1/messages?folder=fld_01j8z9inbox&limit=25" \
  -H "Authorization: Bearer vak_live_..."

{
  "data": [ ... ],
  "pagination": { "next_cursor": "eyJ1aWQiOjQyMTF9", "has_more": true, "limit": 25 },
  "meta": { "request_id": "req_01j8z9..." }
}

Pass next_cursor back as ?cursor= until has_more is false. Stop on has_more, not on an empty page.

Why not an offset

New mail arriving while you page would shift every offset by one, so ?offset=50 silently skips a message and repeats another. A cursor points at a position in the data rather than a count from the start, so it stays correct while the collection changes underneath you.

Limits

limit defaults to 25 and caps at 100. A larger value is clamped rather than rejected, so a client asking for 1000 gets 100 instead of an error.

Cursors expire

A cursor is opaque and short-lived. One that is no longer valid returns 410 cursor_expired, which means start the listing again rather than retry. A cursor that never decoded at all is 400 invalid_cursor: two codes because the fixes differ.

No totals

There is no total count. Across a proxied backend it would be either a lie or an expensive scan, and once published it could not be withdrawn.