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

# API Reference

> Understand the Risoluto API surface before you drill into individual endpoints: base URL, auth rules, response format, and the main endpoint groups.

Risoluto exposes a JSON HTTP API for orchestrator state, issue control, configuration, secrets, workspaces, templates, audit data, and real-time events.

Use this page to get oriented before you dive into individual endpoints.

<Info>
  The dashboard and setup wizard both use this same API. Start Risoluto locally, then open the Swagger UI at
  `http://127.0.0.1:4000/api/docs` or fetch the OpenAPI spec from `http://127.0.0.1:4000/api/v1/openapi.json`.
</Info>

## At a glance

| Item                   | Value                   |
| ---------------------- | ----------------------- |
| **Base URL**           | `http://127.0.0.1:4000` |
| **Versioned API root** | `/api/v1`               |
| **Streaming events**   | `GET /api/v1/events`    |
| **Metrics**            | `GET /metrics`          |

Most local requests on loopback work without extra auth. If you expose Risoluto remotely, mutating requests need a write token.

## Authentication

| Scenario                                           | Requirement                              |
| -------------------------------------------------- | ---------------------------------------- |
| Loopback requests (`127.0.0.1`, `::1`)             | No auth required                         |
| Remote read-only (`GET`, `HEAD`, `OPTIONS`)        | No auth required                         |
| Remote mutating (`POST`, `PUT`, `PATCH`, `DELETE`) | `Authorization: Bearer <token>` required |

Set the token with `RISOLUTO_WRITE_TOKEN` before starting the service:

```bash theme={null}
export RISOLUTO_WRITE_TOKEN="your-secret-token"
```

<Tip>
  If you are operating locally, you can usually explore the API and dashboard without setting a write token first.
</Tip>

## Common first requests

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

  ```javascript JavaScript theme={null}
  const res = await fetch("http://127.0.0.1:4000/api/v1/state");
  const state = await res.json();
  console.log(state);
  ```

  ```python Python theme={null}
  import requests

  state = requests.get("http://127.0.0.1:4000/api/v1/state").json()
  print(state)
  ```
</CodeGroup>

For a mutating request from a remote client, send your bearer token:

```bash theme={null}
curl -X POST http://127.0.0.1:4000/api/v1/refresh \
  -H "Authorization: Bearer $RISOLUTO_WRITE_TOKEN"
```

## Response and error format

Successful responses return the relevant JSON payload directly:

```json theme={null}
{
  "version": "1.2.0",
  "uptime": 3600,
  "issues": []
}
```

Errors follow a consistent envelope:

```json theme={null}
{
  "error": "Issue not found",
  "status": 404
}
```

## Rate limits

| Scope                                | Limit                              |
| ------------------------------------ | ---------------------------------- |
| API endpoints (`/api/*`, `/metrics`) | 300 requests per minute per client |
| Webhooks (`/webhooks/*`)             | 600 requests per minute per client |

When a client exceeds the limit, Risoluto returns `429 Too Many Requests` with a `Retry-After` header.

## Endpoint groups

<CardGroup cols={2}>
  <Card title="State & Metrics" icon="gauge" href="/api-reference/endpoints#state--metrics">
    Read runtime state, metrics, transitions, models, and the live event stream.
  </Card>

  <Card title="Issues" icon="circle-dot" href="/api-reference/endpoints#issue-management">
    Inspect one issue, abort work, override models, steer a run, or transition tracker state.
  </Card>

  <Card title="Attempts" icon="clock-rotate-left" href="/api-reference/endpoints#attempts">
    Review run history and event timelines for past or current attempts.
  </Card>

  <Card title="Configuration" icon="sliders" href="/api-reference/endpoints#configuration">
    Read the effective config, inspect the schema, and manage overlay values.
  </Card>

  <Card title="Secrets" icon="key" href="/api-reference/endpoints#secrets">
    List, set, and delete encrypted runtime secrets.
  </Card>

  <Card title="Workspaces & Git" icon="code-branch" href="/api-reference/endpoints#workspaces--git">
    Inspect workspaces, clean them up, and read repository context.
  </Card>
</CardGroup>

## What's next

* [All Endpoints](/api-reference/endpoints) — browse the full surface area
* [Quickstart](/quickstart) — start the local service before testing endpoints
* [Configuration Reference](/guides/configuration) — understand the settings exposed through the API
* [Observability](/operating/observability) — use metrics and runtime signals in production