REST API (v2)
Pagination & fields
Cursor semantics, limits, field projection, and locale filtering.
Pagination & fields
Shared cross-endpoint behavior. Applies to list endpoints and is mirrored by the MCP counterparts.
Pagination
List endpoints return an opaque cursor — a base64-encoded token the client passes back to fetch the next page.
Request parameters
| Query param | Default | Range | Description |
|---|---|---|---|
limit | 50 | 1 – 200 | Page size. Non-integer or out-of-range → bad_request. |
cursor | (empty) | opaque | Omit for the first page. On follow-up pages, pass the meta.next_cursor from the previous response. |
Response
{
"ok": true,
"elements": [ "..." ],
"meta": {
"total": 127,
"returned": 50,
"next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}
}
meta.next_cursor is null on the last page. Cursors are opaque — do not decode, rely on format, or manipulate. Cursors are version-scoped; discard them when the schema version changes.
Invalid cursor
{
"ok": false,
"errors": [
{
"code": "bad_request",
"message": "Invalid pagination cursor.",
"fix_hint": "Discard the cursor and re-issue the request without one, or pass a value previously returned by the API."
}
]
}
Field projection
Endpoints that return element rows accept a fields parameter.
| Value | Meaning |
|---|---|
?fields=id,title,category_id | Comma-separated field names. id is always included. |
?fields=all | Return the full element record. |
| (omitted) | Endpoint-specific default. /elements uses ["id","title","category_id"]; /elements/:id uses "all". |
Unknown field names are silently ignored — you can write feature-detected projection lists safely.
Locale filtering
Localized fields have the shape [{ "locale": "en", "value": "…" }, { "locale": "fr", "value": "…" }]. The locales query parameter trims these arrays.
| Value | Meaning |
|---|---|
?locales=en | Retain only English entries. |
?locales=en,fr | Retain English and French. |
| (omitted) | Return every locale. |
Unknown locale codes (?locales=zz) are tolerated; the filter simply removes nothing for them.