Documentation Index
Fetch the complete documentation index at: https://docs.risolu.to/llms.txt
Use this file to discover all available pages before exploring further.
State & Metrics
Core orchestrator state, runtime metadata, real-time events, and observability.
| Method | Path | Description |
|---|
GET | /api/v1/state | Full orchestrator snapshot — queued, running, completed issues and token totals |
GET | /api/v1/runtime | Runtime info — version, data directory, feature flags |
GET | /api/v1/observability | Aggregate observability snapshot — metrics summaries and health signals |
GET | /api/v1/recovery | Latest startup recovery report — orphaned attempts resolved on boot |
POST | /api/v1/refresh | Trigger an immediate poll/reconciliation cycle |
GET | /api/v1/transitions | Available state machine transitions per issue |
GET | /metrics | Prometheus-format service metrics |
GET | /api/v1/events | SSE stream of real-time orchestrator events |
GET | /api/v1/models | List available AI models from the configured provider |
POST /api/v1/refresh returns 202 Accepted, not 200. The reconciliation runs asynchronously.
curl http://127.0.0.1:4000/api/v1/state
Issue Management
Inspect individual issues, control running agents, override models and templates, and transition issue state.
| Method | Path | Description |
|---|
GET | /api/v1/:id | Issue detail with recent events and attempts |
POST | /api/v1/:id/abort | Abort a running issue |
POST | /api/v1/:id/model | Set per-issue model override |
POST | /api/v1/:id/steer | Send mid-turn guidance to the running agent |
POST | /api/v1/:id/template | Override the prompt template for this issue |
DELETE | /api/v1/:id/template | Clear the template override |
POST | /api/v1/:id/transition | Transition issue to a new workflow state |
The :id parameter is the Linear issue identifier (e.g. ENG-123).
Model Override
The model identifier to use for this issue (e.g. o4-mini, gpt-4.1).
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/model \
-H "Content-Type: application/json" \
-d '{"model": "o4-mini"}'
Mid-Turn Steering
Guidance text injected into the running agent’s context.
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/steer \
-H "Content-Type: application/json" \
-d '{"message": "Focus on the auth module first, skip the tests for now."}'
State Transition
Target state name. Use GET /api/v1/transitions to see valid transitions.
Optional human-readable reason for the transition.
curl -X POST http://127.0.0.1:4000/api/v1/ENG-123/transition \
-H "Content-Type: application/json" \
-d '{"to": "queued", "reason": "Retry after fix"}'
Attempts
Each issue can have multiple attempts. An attempt represents a single agent execution run.
| Method | Path | Description |
|---|
GET | /api/v1/:id/attempts | List all attempts for an issue |
GET | /api/v1/attempts/:aid | Detail for a specific attempt including event timeline |
GET | /api/v1/attempts/:aid/checkpoints | Checkpoint history for an attempt — progress markers written by the agent runner |
curl http://127.0.0.1:4000/api/v1/ENG-123/attempts
Configuration
Read the effective merged config, inspect the schema, and manage runtime overlay overrides.
| Method | Path | Description |
|---|
GET | /api/v1/config | Effective merged configuration (base + overlay) |
GET | /api/v1/config/schema | Config JSON schema with example payloads |
GET | /api/v1/config/overlay | Current overlay values only |
PUT | /api/v1/config/overlay | Replace the entire overlay |
PATCH | /api/v1/config/overlay/:path | Patch a single config path |
DELETE | /api/v1/config/overlay/:path | Delete a specific overlay path |
The overlay is persisted to disk and survives restarts. It merges on top of the base config file and environment variables.
curl http://127.0.0.1:4000/api/v1/config
Secrets
Manage runtime secrets without restarting the service. Secrets are encrypted at rest.
| Method | Path | Description |
|---|
GET | /api/v1/secrets | List configured secret keys (values are not exposed) |
POST | /api/v1/secrets/:key | Store a secret |
DELETE | /api/v1/secrets/:key | Delete a secret |
GET /api/v1/secrets returns key names only, never the secret values.
curl http://127.0.0.1:4000/api/v1/secrets
Templates
Manage prompt templates for agent instructions. Templates support variable interpolation.
| Method | Path | Description |
|---|
GET | /api/v1/templates | List all prompt templates |
GET | /api/v1/templates/:id | Get a specific template |
POST | /api/v1/templates | Create a new template |
PUT | /api/v1/templates/:id | Update an existing template |
DELETE | /api/v1/templates/:id | Delete a template |
POST | /api/v1/templates/:id/preview | Preview rendered output with sample variables |
curl http://127.0.0.1:4000/api/v1/templates
Workspaces & Git
Inspect and manage the working directory pool and git routing context.
| Method | Path | Description |
|---|
GET | /api/v1/workspaces | List workspaces with disk usage |
DELETE | /api/v1/workspaces/:key | Remove a workspace and free disk |
GET | /api/v1/git/context | Git repo context — branches, remotes, routing rules |
curl http://127.0.0.1:4000/api/v1/workspaces
Audit
Paginated audit log of all orchestrator actions for compliance and debugging.
| Method | Path | Description |
|---|
GET | /api/v1/audit | Query audit log entries (supports pagination) |
curl "http://127.0.0.1:4000/api/v1/audit?limit=50&offset=0"
Notifications
Persistent notification timeline for run lifecycle alerts. Backed by the notification store and deduplicated per run.
| Method | Path | Description |
|---|
GET | /api/v1/notifications | List persisted notifications. Supports limit and unread query parameters |
POST | /api/v1/notifications/:id/read | Mark a single notification as read |
POST | /api/v1/notifications/read-all | Mark every notification as read |
POST | /api/v1/notifications/test | Send a test Slack notification using the saved webhook |
curl "http://127.0.0.1:4000/api/v1/notifications?unread=true&limit=50"
The test endpoint reuses the Slack webhook configured under notifications.channels in your config overlay. See Notifications setup for channel configuration.
Automations
Scheduled background automations — scheduler inspection and on-demand runs.
| Method | Path | Description |
|---|
GET | /api/v1/automations | List configured automations and current scheduler state |
GET | /api/v1/automations/runs | Historical automation runs. Supports limit and automation_name filters |
POST | /api/v1/automations/:name/run | Run a configured automation immediately |
curl -X POST http://127.0.0.1:4000/api/v1/automations/nightly-cleanup/run
Alerts
Alert delivery history — each row records a rule evaluation, trigger, or cooldown event.
| Method | Path | Description |
|---|
GET | /api/v1/alerts/history | Paginated alert history. Supports limit and rule_name filters |
curl "http://127.0.0.1:4000/api/v1/alerts/history?limit=100"
Webhooks
Inbound webhook receivers for external integrations and an authenticated trigger dispatcher.
| Method | Path | Description |
|---|
POST | /webhooks/linear | Linear webhook receiver — processes issue and comment events |
POST | /webhooks/github | GitHub webhook receiver — processes repository and pull request events |
POST | /api/v1/webhooks/trigger | Dispatch an authenticated trigger action from an external system |
Inbound receivers (/webhooks/linear, /webhooks/github) have a separate rate limit of 600 requests/minute. Configure the webhook URL in the corresponding provider’s workspace settings. POST /api/v1/webhooks/trigger requires the configured trigger credentials.
Codex Operator
Operator routes that proxy to the embedded Codex control plane. Each route forwards to a JSON-RPC method on the Codex app-server session. See Runtime concepts for context on the control-plane session lifecycle.
Session state
| Method | Path | Description |
|---|
GET | /api/v1/codex/capabilities | Control-plane feature flags and reported capabilities |
GET | /api/v1/codex/features | List Codex experimental features. Supports limit and cursor |
GET | /api/v1/codex/collaboration-modes | List available Codex collaboration modes |
MCP servers
| Method | Path | Description |
|---|
GET | /api/v1/codex/mcp | List MCP servers registered with Codex. Supports limit and cursor |
POST | /api/v1/codex/mcp/oauth/login | Begin an OAuth login flow for a named MCP server |
POST | /api/v1/codex/mcp/reload | Reload the MCP server configuration |
Threads
| Method | Path | Description |
|---|
GET | /api/v1/codex/threads | List Codex threads. Supports limit, cursor, sortKey, archived, modelProviders, and sourceKinds |
GET | /api/v1/codex/threads/loaded | List threads currently loaded in memory |
GET | /api/v1/codex/threads/:threadId | Read a single thread. Pass includeTurns=true to return turn history |
POST | /api/v1/codex/threads/:threadId/fork | Fork a thread into a new session |
POST | /api/v1/codex/threads/:threadId/name | Rename a thread |
POST | /api/v1/codex/threads/:threadId/archive | Archive a thread |
POST | /api/v1/codex/threads/:threadId/unarchive | Unarchive a thread |
POST | /api/v1/codex/threads/:threadId/unsubscribe | Unsubscribe from a thread’s event stream |
Account
| Method | Path | Description |
|---|
GET | /api/v1/codex/account | Read the current Codex account |
GET | /api/v1/codex/account/rate-limits | Read Codex account rate-limit state |
POST | /api/v1/codex/account/login/start | Start a Codex login flow. Accepts type and apiKey |
POST | /api/v1/codex/account/login/cancel | Cancel an in-progress login by loginId |
POST | /api/v1/codex/account/logout | Log out of the Codex account |
| Method | Path | Description |
|---|
GET | /api/v1/codex/requests/user-input | List pending user-input requests awaiting operator response |
POST | /api/v1/codex/requests/user-input/:requestId/respond | Respond to a pending request with a result payload |
All Codex routes return 503 when the control plane is not configured or is unreachable, 502 when the underlying Codex request fails, and 501 when the requested method is not supported by the installed Codex version.
Docs & Spec
Machine-readable API specification and interactive documentation.
| Method | Path | Description |
|---|
GET | /api/v1/openapi.json | OpenAPI 3.0 specification |
GET | /api/docs | Swagger UI — interactive API explorer |
curl http://127.0.0.1:4000/api/v1/openapi.json | jq .info
What’s Next
