API reference

Errors & pagination

These conventions are uniform across the operator REST API, so you can write one client and reuse it everywhere.

Status codes

The API uses standard HTTP status codes:

Code	Meaning
`200 OK`	Request succeeded; body carries the result.
`201 Created`	A resource was created (e.g. an artifact published, a rollout started).
`202 Accepted`	The request was queued and will be fulfilled later - a device log request is fulfilled on the device's next heartbeat.
`204 No Content`	Success with no body - used by login, logout, and most updates and deletes.
`400 Bad Request`	The input was malformed or invalid (bad field, unsupported value).
`401 Unauthorized`	No valid session cookie or API key.
`403 Forbidden`	Authenticated, but the credential lacks the permission the route requires.
`404 Not Found`	The named resource does not exist or is not visible to you.
`409 Conflict`	The request collides with current state - for example a duplicate artifact version.

Error shape

Errors return a JSON object with a single human-readable error field:

{ "error": "name and version must match the required pattern" }

A 403 names the exact permission that is missing, so you can see precisely what a credential's role lacks:

{ "error": "missing permission: rollouts.write" }

Permissions

Every endpoint is gated on the permission it needs: reads want a read permission (devices.read, artifacts.read), state changes want the matching write or manage permission. API keys run day-to-day fleet operations but can't administer users or keys. On a 403, grant the role the named permission rather than working around it.

Pagination

List endpoints - devices, artifacts, rollouts, and others - page server-side using two query parameters:

Parameter	Default	Notes
`limit`	`50`	Maximum items per page; values above `200` are clamped to `200`.
`offset`	`0`	Number of items to skip from the start of the result.

A paginated response carries the page of items alongside the totals you need to drive a pager:

{
  "devices": [ /* ... up to `limit` items ... */ ],
  "total": 1280,
  "limit": 50,
  "offset": 100,
  "counts": { "online": 940, "offline": 320, "decommissioned": 20 }
}

total counts items matching your filter; counts breaks down the whole set for summary tiles. To walk a full list, advance offset by limit until you've read total items.

Filtering

List endpoints filter server-side via query parameters, so you never download more than you need. Available filters depend on the resource - commonly a free-text query (q) plus narrowing like device status, artifact kind, or vulnerability severity. Combine them with limit/offset; the returned total reflects the filtered set.