REST API overview
Everything you can do in the console you can also do over a REST API. It is the operator-facing surface: enrolling devices, publishing signed artifacts, driving rollouts, and pulling compliance evidence. It is the same API the dashboard uses, so nothing is hidden behind the UI.
This is distinct from the device-facing API. Operators and automation talk to the REST API; the agent on each device talks to a separate, mTLS-only gRPC service covered in Device gRPC API.
Base path and versioning
All endpoints live under a versioned prefix:
https://<your-domain>/api/v1/...
Requests and responses are JSON unless an endpoint deals in files — SBOM uploads, report PDFs, and log bundles are sent and returned as their native content types.
Authentication
Two credentials are accepted, and most endpoints take either:
- Session cookie — issued by
POST /api/v1/auth/loginand stored as an httpOnly cookie. This is what the browser console uses. - API key — a bearer token for automation. Send it as
Authorization: Bearer <key>. Create keys in the console; the plaintext is shown once at creation and only its hash is stored.
curl https://<your-domain>/api/v1/devices \
-H "Authorization: Bearer <your-api-key>"
A few endpoints are deliberately session-only: creating users, and managing API keys and enrollment-token administration in some flows. This is by design — a leaked key must not be able to mint more keys or new users. API keys carry an operator-level permission set; they cannot perform user or key administration even though they can do day-to-day fleet work.
What the API covers
| Area | Endpoints |
|---|---|
| Auth & profile | POST /auth/login, POST /auth/logout, GET /auth/me, GET/PATCH /profile |
| Devices | GET /devices, GET /devices/{name}/history, DELETE /devices/{name}, device log request/download |
| Enrollment | POST /enroll-tokens, GET /enroll-tokens, DELETE /enroll-tokens/{id} |
| Artifacts | POST /artifacts, GET /artifacts, PATCH /artifacts/{id}, SBOM attach/download |
| Registries | POST /registries, GET /registries, tag browse and import |
| Groups & rollouts | POST /groups, POST /rollouts, rollout approve / resume / abort, rollout detail |
| Evidence & compliance | incident reporting, audit-trail export, readiness and vulnerability reports |
| Administration | API keys, users, report branding |
Each endpoint is gated on the specific permission it needs, so a viewer-scoped credential can read but not change the fleet. A request lacking the permission for a route is rejected with a clear message naming the missing permission.
Conventions
- Publishing is always signed. When you publish an artifact, it is added to the update-signing repository before any record of it exists. There is no unsigned publish path.
- Metadata only. The platform records artifact metadata, SBOMs you attach, and audit events. It never inspects or exports the contents of your application or model payloads.
- Pagination and errors are uniform across list endpoints — see Errors & pagination.