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 specific permission it needs. Read endpoints require a read permission for their area (for example devices.read or artifacts.read); the actions that change state require the corresponding write or manage permission. API keys carry an operator-level set — enough to run day-to-day fleet operations, but not to administer users or other keys. If a request is rejected with 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 is the count of items matching your filter; counts is a breakdown for the whole set, handy for summary tiles. To walk a full list, request successive pages by advancing offset by limit until you have read total items.

Filtering

List endpoints accept filters as query parameters, applied server-side so you never download more than you need. Available filters depend on the resource — common ones include a free-text query (q), and resource-specific narrowing such as device status, artifact kind, or vulnerability severity. Combine filters with limit and offset; the returned total reflects the filtered set.