All Endpoints - Risoluto

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

curl -X POST http://127.0.0.1:4000/api/v1/refresh
# → 202 Accepted

curl -N http://127.0.0.1:4000/api/v1/events
# SSE stream — keep connection open

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

string

required

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

string

required

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

string

required

Target state name. Use GET /api/v1/transitions to see valid transitions.

string

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

curl http://127.0.0.1:4000/api/v1/attempts/att_01234

curl http://127.0.0.1:4000/api/v1/attempts/att_01234/checkpoints

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

curl -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H "Content-Type: application/json" \
  -d '{"polling_interval_seconds": 30, "max_concurrent": 3}'

curl -X DELETE http://127.0.0.1:4000/api/v1/config/overlay/polling_interval_seconds

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

curl -X POST http://127.0.0.1:4000/api/v1/secrets/OPENAI_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"value": "sk-..."}'

curl -X DELETE http://127.0.0.1:4000/api/v1/secrets/OPENAI_API_KEY

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

curl -X POST http://127.0.0.1:4000/api/v1/templates \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bug-fix",
    "body": "Fix the bug described in {{issue.title}}. Focus on {{issue.labels}}."
  }'

curl -X POST http://127.0.0.1:4000/api/v1/templates/tpl_01234/preview \
  -H "Content-Type: application/json" \
  -d '{"variables": {"issue": {"title": "Login crash", "labels": ["bug"]}}}'

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

curl -X DELETE http://127.0.0.1:4000/api/v1/workspaces/ws_abc123

curl http://127.0.0.1:4000/api/v1/git/context

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"

curl -X POST http://127.0.0.1:4000/api/v1/notifications/ntf_01234/read

curl -X POST http://127.0.0.1:4000/api/v1/notifications/test

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

Interactive input

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

API Overview — authentication, rate limits, and quick-start examples
Configuration Guide — config file format and environment variables
Observability — Prometheus metrics and alerting setup
Troubleshooting — common issues and solutions

​State & Metrics

​Issue Management

​Model Override

​Mid-Turn Steering

​State Transition

​Attempts

​Configuration

​Secrets

​Templates

​Workspaces & Git

​Audit

​Notifications

​Automations

​Alerts

​Webhooks

​Codex Operator

​Session state

​MCP servers

​Threads

​Account

​Interactive input

​Docs & Spec

​What’s Next

State & Metrics

Issue Management

Model Override

Mid-Turn Steering

State Transition

Attempts

Configuration

Secrets

Templates

Workspaces & Git

Audit

Notifications

Automations

Alerts

Webhooks

Codex Operator

Session state

MCP servers

Threads

Account

Interactive input

Docs & Spec

What’s Next