API reference
The full reference of the user-facing REST API lives in the repository:
docs/API.md.
Here is what you need to know before the first request.
Base and format
All paths are relative to /api/v1, format is JSON. Responses and error
codes are in English; the interface language is the client's concern.
Authentication
| Subject | Mechanism |
|---|---|
| Human | Authorization: Bearer <access token>, 15 minutes |
| Browser | same header + refresh in an httpOnly cookie |
| Machine | a separate token from /machine/login, scoped to "project × environment" |
The X-Client header (web, cli, sdk, mobile) is recorded in the
audit and decides where the refresh token ends up: the browser only gets it
in a cookie.
Errors
{ "error": { "code": "VALIDATION", "message": "..." } }
Branch on code, not on the text. Every response carries an X-Request-Id —
that is the only thing you need to quote in a support request.
Pagination
{ "items": [...], "nextCursor": "..." }. The cursor is opaque: pass it back
in ?cursor= as long as it keeps coming.
A common mistake
GET /projects requires ?orgId= — without it the response is VALIDATION.