HTTP API reference
The Cayu HTTP control plane. Download the OpenAPI schema for exact request and response models, required fields, enum values, validation bounds and response content types.
Configuration and authentication
Section titled “Configuration and authentication”This reference is generated by constructing the released server with ServerConfig.local_development() and in-memory stores; it does not launch a listener or contact providers. The schema describes its default route groups. Optional browser-control and other application-selected capabilities can add routes; application policies can disable groups. Use your configured server’s schema for those variations.
For local development, run cayu serve --dev --host 127.0.0.1 and open /cayu/. Deployed servers require ServerConfig.protected(...) or a configured authentication target. Authentication, business authorization and tenant isolation are separate decisions. AuthContext.tenant is operator provenance; it does not filter stored data.
Requests and responses
Section titled “Requests and responses”Paths below include the default /api prefix. Embedding under a host mount can add another prefix. Inspect operation-specific success/error schemas. Streaming endpoints can return text/event-stream; consume events incrementally and follow the declared terminal behavior. A successful HTTP response does not establish that a requested run or external effect completed.
Endpoint groups
Section titled “Endpoint groups”| Group | Operations |
|---|---|
| agents | 2 |
| artifacts | 3 |
| causal-budgets | 3 |
| contract | 1 |
| diagnostics | 1 |
| environments | 2 |
| event-side-effects | 2 |
| health | 1 |
| knowledge | 4 |
| operations | 1 |
| pending-actions | 1 |
| provider-operations | 1 |
| recovery | 1 |
| resume | 1 |
| run | 1 |
| sessions | 25 |
| system | 1 |
| tasks | 9 |
| tool-approvals | 2 |
| tool-rounds | 1 |
| usage | 1 |
| user-input | 2 |
Error handling
Section titled “Error handling”Validation failures are described by the operation’s HTTP validation schema. Authentication failures use the configured access policy. Domain conflicts, unavailable state and runtime failures carry their own typed evidence; read the response body and the session’s durable events before deciding whether a retry is safe. Use idempotency and reconciliation for mutations with an uncertain downstream outcome.