> ## 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.

# All Endpoints

> Complete reference of all Risoluto REST API endpoints — state, issues, attempts, config, secrets, templates, workspaces, audit, and webhooks.

## 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                           |

<Tip>
  `POST /api/v1/refresh` returns **202 Accepted**, not 200. The reconciliation runs asynchronously.
</Tip>

<CodeGroup>
  ```bash "Get state" theme={null}
  curl http://127.0.0.1:4000/api/v1/state
  ```

  ```bash "Trigger refresh" theme={null}
  curl -X POST http://127.0.0.1:4000/api/v1/refresh
  # → 202 Accepted
  ```

  ```bash "Stream events" theme={null}
  curl -N http://127.0.0.1:4000/api/v1/events
  # SSE stream — keep connection open
  ```
</CodeGroup>

***

## 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     |

<Note>
  The `:id` parameter is the Linear issue identifier (e.g. `ENG-123`).
</Note>

### Model Override

<ParamField body="model" type="string" required>
  The model identifier to use for this issue (e.g. `o4-mini`, `gpt-4.1`).
</ParamField>

```bash theme={null}
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

<ParamField body="message" type="string" required>
  Guidance text injected into the running agent's context.
</ParamField>

```bash theme={null}
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

<ParamField body="to" type="string" required>
  Target state name. Use `GET /api/v1/transitions` to see valid transitions.
</ParamField>

<ParamField body="reason" type="string">
  Optional human-readable reason for the transition.
</ParamField>

```bash theme={null}
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 |

<CodeGroup>
  ```bash "List attempts" theme={null}
  curl http://127.0.0.1:4000/api/v1/ENG-123/attempts
  ```

  ```bash "Attempt detail" theme={null}
  curl http://127.0.0.1:4000/api/v1/attempts/att_01234
  ```

  ```bash "Checkpoint history" theme={null}
  curl http://127.0.0.1:4000/api/v1/attempts/att_01234/checkpoints
  ```
</CodeGroup>

***

## 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                  |

<Tip>
  The overlay is persisted to disk and survives restarts. It merges on top of the base config file and environment variables.
</Tip>

<CodeGroup>
  ```bash "Read effective config" theme={null}
  curl http://127.0.0.1:4000/api/v1/config
  ```

  ```bash "Update overlay" theme={null}
  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}'
  ```

  ```bash "Delete overlay path" theme={null}
  curl -X DELETE http://127.0.0.1:4000/api/v1/config/overlay/polling_interval_seconds
  ```
</CodeGroup>

***

## 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                                      |

<Warning>
  `GET /api/v1/secrets` returns key names only, never the secret values.
</Warning>

<CodeGroup>
  ```bash "List keys" theme={null}
  curl http://127.0.0.1:4000/api/v1/secrets
  ```

  ```bash "Set a secret" theme={null}
  curl -X POST http://127.0.0.1:4000/api/v1/secrets/OPENAI_API_KEY \
    -H "Content-Type: application/json" \
    -d '{"value": "sk-..."}'
  ```

  ```bash "Delete a secret" theme={null}
  curl -X DELETE http://127.0.0.1:4000/api/v1/secrets/OPENAI_API_KEY
  ```
</CodeGroup>

***

## 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 |

<CodeGroup>
  ```bash "List templates" theme={null}
  curl http://127.0.0.1:4000/api/v1/templates
  ```

  ```bash "Create template" theme={null}
  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}}."
    }'
  ```

  ```bash "Preview render" theme={null}
  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"]}}}'
  ```
</CodeGroup>

***

## 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 |

<CodeGroup>
  ```bash "List workspaces" theme={null}
  curl http://127.0.0.1:4000/api/v1/workspaces
  ```

  ```bash "Remove workspace" theme={null}
  curl -X DELETE http://127.0.0.1:4000/api/v1/workspaces/ws_abc123
  ```

  ```bash "Git context" theme={null}
  curl http://127.0.0.1:4000/api/v1/git/context
  ```
</CodeGroup>

***

## 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) |

```bash theme={null}
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                       |

<CodeGroup>
  ```bash "List unread" theme={null}
  curl "http://127.0.0.1:4000/api/v1/notifications?unread=true&limit=50"
  ```

  ```bash "Mark one read" theme={null}
  curl -X POST http://127.0.0.1:4000/api/v1/notifications/ntf_01234/read
  ```

  ```bash "Send Slack test" theme={null}
  curl -X POST http://127.0.0.1:4000/api/v1/notifications/test
  ```
</CodeGroup>

<Tip>
  The test endpoint reuses the Slack webhook configured under `notifications.channels` in your config overlay. See [Notifications setup](/guides/notifications) for channel configuration.
</Tip>

***

## 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                                    |

```bash "Run an automation now" theme={null}
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 |

```bash "Recent alerts" theme={null}
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       |

<Tip>
  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.
</Tip>

***

## 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](/concepts/runtime) 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        |

<Warning>
  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.
</Warning>

***

## 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 |

```bash theme={null}
curl http://127.0.0.1:4000/api/v1/openapi.json | jq .info
```

***

## What's Next

* [API Overview](/api-reference/overview) — authentication, rate limits, and quick-start examples
* [Configuration Guide](/guides/configuration) — config file format and environment variables
* [Observability](/operating/observability) — Prometheus metrics and alerting setup
* [Troubleshooting](/operating/troubleshooting) — common issues and solutions