Versioning
All routes live under /v1. The v1 contract evolves additively only; breaking changes would ship as /v2 side by side. The complete route table is generated from the shared contracts and published as the API reference.
Authentication modes
| Mode | Used by | Credential |
|---|---|---|
user | console, CLI, SDK, CI pipelines | user session / access token, checked against role permissions |
agent | customer-resident agents | short-lived access token obtained with a signed assertion |
enrollment | first agent start | one-time, short-lived enrollment token |
public | health check, website lead form | none |
Tokens are sent in the Authorization header only. They never appear in URLs or message bodies and are never logged.
Errors
Every non-2xx response has the same shape: a machine code (for example VALIDATION_FAILED, FORBIDDEN, NOT_FOUND), a human-readable message, a correlation_id for support, and optional details listing the field path and a code for each problem. Error responses never echo the values you submitted.
Pagination
List endpoints return {"items": [...], "page": {"limit": n, "next_cursor": "..."}}. Pass the cursor back to fetch the next page; cursors are opaque.
Idempotency
Routes marked idempotent in the reference accept an Idempotency-Key header. Retrying with the same key returns the original result instead of creating a duplicate — use this from CI pipelines and scripts.
OpenAPI and SDKs
The OpenAPI 3.1 document, the typed Python and TypeScript SDKs, retry rules and code examples are described in SDKs and OpenAPI.