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:
- 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.
- Deep page cost.
OFFSET 50000tells 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
curl "https://acme.crm.blesyum.app/api/crm/public/v1/contacts?per_page=50" \
-H "Authorization: Bearer blsk_..."{
"type": "list",
"data": [ … ],
"pages": {
"type": "pages",
"per_page": 50,
"next": { "starting_after": "eyJjIjoxNzY0…" }
}
}Next page:
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
| Parameter | Default | Maximum |
|---|---|---|
per_page | 50 | 150 |
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.