API overview
The REST API — base path, the OpenAPI document generated from the same contracts that validate requests, errors, idempotency and live updates.
- Base path:
/api/v1. - OpenAPI:
GET /api/v1/openapi.jsonon any installation. It is generated from the same Zod contracts that validate requests, so it cannot drift from the implementation. This site's API reference renders a copy of it. - Contracts are shared by the API, the web app, the worker, the CLI and the mobile app.
Organization-scoped resources
Everything owned by an organization lives under /orgs/:orgId/…: projects, tasks (with /events and
/actions), workers, capabilities, capability-installations, providers, secrets, members,
invitations, teams, audit, notifications, usage, overview, integrations, github. The server checks
membership and role on every request; non-members get 404, so organization ids cannot be probed.
Errors
{ "error": { "code": "INVALID_TRANSITION", "message": "…", "correlationId": "cor_…", "retryable": false, "context": {} } }Every response carries x-correlation-id. Unknown server errors never include internal details.
Idempotency
POST /orgs/:orgId/tasksacceptsidempotencyKeyin the body or anIdempotency-Keyheader: the same key returns the same task.- Worker transitions carry a
transitionIdand events aneventId; replays are no-ops.
Live updates
GET /api/v1/live (WebSocket). The first message must be
{"type":"auth","token":"<accessToken>","organizationId":"…"}. The server then streams task.updated,
task.event, worker.updated and notification messages for that organization.
Rate limits
300 requests per minute per client by default, 20 on sign-in routes (configurable on self-hosted installations).