ConnectCloud Developers

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"
  1. Store the start time of a sync run before the first request.
  2. Page through all results with cursor.
  3. Use the stored start time as updatedSince of the next run; overlapping a few seconds is fine because the result is idempotent per item id and version.

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.

View as Markdown