Pagination and delta sync
List endpoints return one page at a time, always as an object – never a bare array:
{ "items": [ … ], "nextCursor": "eyJ2IjoxLCJzIjoidXBkYXRlZCIsImsiOlsi…", "total": 342 }
| Field | Meaning |
|---|---|
items |
the entries of this page; [] when there are none |
nextCursor |
cursor of the next page; missing on the last page (cursor lists only) |
total |
number of entries for the filter, where the list counts; left out where counting would be expensive |
Two styles exist, and the reference of every list endpoint shows which one it uses and its limits:
- Cursor (keyset) pagination for collections that keep growing (tickets, items, events, documents, messages): stable while data changes, no skipped or repeated entries.
- Offset pagination for bounded lists (settings, groups, configuration).
limit and offset are checked, never adjusted silently: a value that is not a whole number or lies outside the
documented range is a 400 invalid naming the parameter in field (limit, offset, cursor). The search API
pages its hits with from and size (see its reference) under the same rule; from + size is at most 500 (it was
10,000 until November 2026), so a search reaches its 500 best hits.
Cursor pagination (desk, forge)
Desk and forge lists take limit and an opaque cursor:
curl "https://api.mbcom.cloud/api/desk/v1/items?space=SUP&limit=100" -H "Authorization: Bearer $ACCESS_TOKEN"
{
"items": [ { "id": "…", "number": 1234, "title": "…" } ],
"nextCursor": "eyJ1IjoiMjAyNi0wMy0wMlQwOTozMDowMFoiLCJpIjoiLi4uIn0",
"total": 342
}
Pass nextCursor as cursor to get the next page; keep every other parameter unchanged. When
nextCursor is missing you have reached the end. limit defaults to 100 in desk (at most 500) and 50 in forge
(at most 200). The entries and the history of a desk ticket page the same way (limit 1–500, default 200); short
lists such as a ticket's links, children or checklist, the configuration lists and the last executions of a desk or
forge automation (at most 50) answer every entry at once ({ "items": [ … ] } without nextCursor). Workflow's instance list (GET /api/workflow/v1/instances) pages the same way (limit 1–500,
default 100); its task list (GET /api/workflow/v1/tasks) takes limit and offset and returns total. The DMS
document list (GET /api/dms/v1/documents) pages by cursor too (limit 1–100, default 50) and returns the total of
the filter; keep sort and the filter unchanged while you follow nextCursor. The CRM lists (leads, opportunities,
activities, campaigns, CSAT feedback) and the master data addresses and articles page by cursor as well (limit
1–200, default 50, with total), whatever their sort.
Trade's growing lists page by cursor, newest first: the sales transactions and contracts, and – with the total of
the filter on every page – purchase orders, goods receipts, inbound invoices, inbound delivery notes, e-invoice checks
and the stock movements of an article.
Cursors are opaque and short-lived: do not store, build or change them. A cursor belongs to the list and
the sort it came from – used with another sort, or altered, it is a 400 invalid with field: "cursor".
Offset pagination (HR, comms)
HR and comms lists take limit (default 50, at most 200) and offset and return total:
curl "https://api.mbcom.cloud/api/hr/v1/employees?status=active&limit=200&offset=200" \
-H "Authorization: Bearer $ACCESS_TOKEN"
{ "items": [ … ], "total": 431 }
Increase offset by limit until offset >= total. Offsets can skip or repeat entries when data
changes while you page; for exports sort by a stable key (e.g. sort=createdAt).
Delta sync
To mirror desk items into another system, do not re-read everything. Remember the time of your last sync and ask only for what changed since:
curl "https://api.mbcom.cloud/api/desk/v1/items?updatedSince=2026-03-02T09:30:00Z&sort=updated&order=asc&limit=500" \
-H "Authorization: Bearer $ACCESS_TOKEN"
- Store the start time of a sync run before the first request.
- Page through all results with
cursor. - Use the stored start time as
updatedSinceof the next run; overlapping a few seconds is fine because the result is idempotent per itemidandversion.
For near-real-time updates combine delta sync with webhooks: the webhook tells you that an item changed, the API gives you its current state.
Filtering and sorting
List endpoints accept filters as query parameters; several values of one filter are
comma-separated (status=open,waiting). Desk filters on custom fields use cf.<key>=<value>.
Sorting uses sort and order (desk) or sort with a - prefix for descending (HR). Filter
values such as statuses, types and priorities are tenant configuration: read them from the
module's bootstrap endpoint instead of hard-coding them.