Reference

API

The versioned REST contract, credentials and conventions.

/api/v1/... is the stable contract: within v1, changes are additive only. The OpenAPI description is at /openapi/v1.json.

CredentialHeaderReaches
API keyAuthorization: Bearer ak_…your organization, by the key's role
App keyAuthorization: Bearer aks_…/api/v1/apps/{installId}/… only, from your server: tokens, records, runs
End-user token or your JWTAuthorization: Bearer aeu_… / your JWT/api/v1/apps/{installId}/… only, as that user
AreaEndpoints
TasksPOST /tasks, POST /tasks/preview, GET /tasks/{id}, /wait, /result, /chat, POST /tasks/{id}/messages (a follow-up), /continue, /replay, /cancel
Task chat controlsPOST /tasks/{id}/compact, PUT/DELETE /tasks/{id}/pin, GET/POST /tasks/{id}/pins, DELETE /tasks/{id}/pins/{pinId}
FeedbackPOST /feedback, GET/PUT /tasks/{id}/feedback, DELETE /tasks/{id}/feedback/{entryId}; operators: GET /admin/feedback, PATCH /admin/feedback/{id}
Workspaces/workspaces, /workspaces/{id}/runs, /triggers, /connections, /policy, /approvals, /audit
SolutionsPOST /solutions/validate, POST /solutions/parse, GET /solutions/{id}/package, POST /solutions (bundle or package), PUT /solutions/{id}, DELETE …?purge=true, /evals, /usage, /publish, /end-user-tokens, /app-keys, /records/{Entity}, GET /solutions/templates[/{name}]
RegistryGET/POST /registry/packages, GET /registry/packages/{name}[/{version}], POST …/{version}/yank
Apps (end users)GET /apps/{id}, /conversations, /conversations/{id}, /conversations/{id}/messages, /records/{Entity}
Apps (your backend, app key)GET /apps/{id}, POST /apps/{id}/end-user-tokens, /records/{Entity}[/{recordId}], POST /apps/{id}/runs, GET /apps/{id}/runs/{runId}?wait=
Data API specificationsGET /solutions/{id}/openapi?format=json (organization credential), GET /apps/{id}/openapi.json or openapi.yaml (scoped app key)
Live eventsGET /ws/events (Server-Sent Events)

Errors are { "error": "…" }, with "errors": [...] listing every problem on validation. A 404 also covers "exists, but in another organization".