Fundamentals

Pagination

Signed cursor pagination — why there is no offset, how the cursor travels, what the limits are.

List endpoints paginate by cursor. There is no page=3 offset parameter, and that is deliberate.

Why not offset

Offset pagination breaks in two places, both silently:

  1. A shifting list. If a record is inserted while you are reading page 2, every record shifts by one; on page 3 you see a record twice, or miss one entirely.
  2. Deep page cost. OFFSET 50000 tells the database to read and discard 50,000 rows; page 40 costs many times what page 1 costs.

A cursor carries "the position of the last record you saw": the list may shift underneath you, but your reading point does not.

Usage

bash
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts?per_page=50" \
  -H "Authorization: Bearer blsk_..."
json
{
  "type": "list",
  "data": [ … ],
  "pages": {
    "type": "pages",
    "per_page": 50,
    "next": { "starting_after": "eyJjIjoxNzY0…" }
  }
}

Next page:

bash
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts?per_page=50&starting_after=eyJjIjoxNzY0…" \
  -H "Authorization: Bearer blsk_..."

When pages.next is absent, the list is done. That is the only stop condition — waiting for an empty data array costs one extra round trip.

The cursor is OPAQUE

The starting_after value is HMAC-signed and you must not parse it:

  • Modify it and the signature fails; you get 400.
  • Its format can change without notice; a client that parses it will break one day.
  • It does not contain a workspace id — scope always comes from the key, so forging a cursor can never reach another tenant's data.

The only thing you should do is send back what you received.

Limits

ParameterDefaultMaximum
per_page50150

Exceeding it gives 400 and parameter_invalid.

Ordering

List endpoints are ordered (created_at DESC, id DESC). The id is a tie-breaker: even for two records created in the same microsecond the order is stable and pages don't shift.

Pulling a whole list? Use per_page=150 and loop until pages.next is gone. Watch the rate limit on each turn — X-RateLimit-Remaining tells you how many requests are left.