Pagination

Every list of the Public API answers one page at a time, oldest first, and says where the next page starts. There are no page numbers and no offsets: a walk from the first page to the last meets every record exactly once, whatever is created or deleted while it runs.

Pages and cursors

A list takes two query parameters:

And answers two fields:

{
  "data": [{ "id": 42, "name": "Northwind Studio" }],
  "next_cursor": "eyJhZnRlciI6NDJ9"
}

• A cursor is opaque. Never build one or read what is in it; a cursor the API did not give is refused with a 422 invalid_request naming cursor, never read as the first page.
• A limit out of range — 0, or 101 — is a 422 naming limit.
• A filter is sent again with every page. The cursor carries no search, status or date: send the same ones with each page, or the walk changes what it walks.
• A record created during a walk comes at its end, since pages follow the order records were created in. A record deleted before its page is reached is simply not on it.

The lists

Every list pages the same way:

• GET /v1/clients — List Clients, narrowed by search.
• GET /v1/documents — List documents, narrowed by type, status, Client, issue date and search.
• GET /v1/payments — List Payments, one document’s with document_id.
• GET /v1/receipts — List Receipts, one document’s with document_id.
• GET /v1/products — List Products, narrowed by search.

An AI assistant’s search tools page the same way, with pages sized for an assistant: see AI assistants (MCP).

Walking every record

Ask for the largest page, and follow next_cursor until it is null. This counts every Client of the Business:

cursor=""
count=0
while :; do
  page=$(curl -s -G https://api.essentio.pro/v1/clients \
    -H "Authorization: Bearer $ESSENTIO_API_KEY" \
    -d limit=100 \
    ${cursor:+-d cursor=$cursor})
  count=$((count + $(echo "$page" | jq '.data | length')))
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done
echo "$count Clients"

A long walk makes many requests: read the rate limit headers and wait for the next minute when X-RateLimit-Remaining reaches 0.