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.
| Credential | Header | Reaches |
|---|---|---|
| API key | Authorization: Bearer ak_… | your organization, by the key's role |
| App key | Authorization: Bearer aks_… | /api/v1/apps/{installId}/… only, from your server: tokens, records, runs |
| End-user token or your JWT | Authorization: Bearer aeu_… / your JWT | /api/v1/apps/{installId}/… only, as that user |
| Area | Endpoints |
|---|---|
| Tasks | POST /tasks, POST /tasks/preview, GET /tasks/{id}, /wait, /result, /chat, POST /tasks/{id}/messages (a follow-up), /continue, /replay, /cancel |
| Task chat controls | POST /tasks/{id}/compact, PUT/DELETE /tasks/{id}/pin, GET/POST /tasks/{id}/pins, DELETE /tasks/{id}/pins/{pinId} |
| Feedback | POST /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 |
| Solutions | POST /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}] |
| Registry | GET/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 specifications | GET /solutions/{id}/openapi?format=json (organization credential), GET /apps/{id}/openapi.json or openapi.yaml (scoped app key) |
| Live events | GET /ws/events (Server-Sent Events) |
Errors are { "error": "…" }, with "errors": [...] listing every problem on validation.
A 404 also covers "exists, but in another organization".