API reference
Octoriq Router API
Every endpoint you can call with an API key, generated from the same contracts the API validates requests against. New here? Start with the quickstart.
Base URL https://api.octoriq.ai
OpenAPI 3.1 (JSON)- Authentication
- Authorization: Bearer <API key>. Keys belong to one environment (development or production) and carry scopes.
- Idempotency
- Send Idempotency-Key on POST /v1/jobs; repeating it returns the same job instead of creating a new one.
- Events
- GET /v1/jobs/{id}/events is Server-Sent Events. Reconnect with Last-Event-ID to replay missed events once.
- Errors
- Errors are application/problem+json with a stable code, so clients branch on code, not on message text.
Jobs
- GET
/v1/jobsList jobs (newest first)jobs:read - POST
/v1/jobsSubmit a goaljobs:write - GET
/v1/jobs/statsJob aggregates over a windowjobs:read - GET
/v1/jobs/{id}/executionsExecutor calls of a job (steps, attempts, cost, normalized errors)jobs:read - GET
/v1/jobs/{id}Get a jobjobs:read - GET
/v1/jobs/{id}/eventsStream job events (Server-Sent Events)jobs:read - POST
/v1/jobs/{id}/cancelRequest cancellation (idempotent; job reaches cancelled asynchronously)jobs:write - POST
/v1/jobs/{id}/feedbackAccept or reject a completed job result (replaces earlier feedback)jobs:write
Billing & usage
- GET
/v1/billingPrepaid credit balance and the latest ledger entriesjobs:read - GET
/v1/billing/reconciliationProvider cost vs customer charge vs credit debit per completed jobjobs:read
Routing insights
- GET
/v1/route-experimentsShadow routes compared with their primaries, with the promotion verdictjobs:read - GET
/v1/agentrankExecutor rankings per capability and route step, from verified outcomesjobs:read
A2A
- GET
/.well-known/agent-card.jsonA2A Agent Card (protocol v1.0): skills = capabilities, JSON-RPC at /a2a - POST
/a2aA2A JSON-RPC 2.0 (A2A-Version: 1.0): SendMessage, SendStreamingMessage, GetTask, CancelTask, SubscribeToTask. A task is a job (task id = job id).jobs:read · jobs:write
System
- GET
/healthLiveness
goal plan route execute verify outcome
Stop managing AI execution. Start building.
One API to route, execute, verify, and observe AI work.