API Reference - Risoluto

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.

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.

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:

export RISOLUTO_WRITE_TOKEN="your-secret-token"

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

Common first requests

curl http://127.0.0.1:4000/api/v1/state

const res = await fetch("http://127.0.0.1:4000/api/v1/state");
const state = await res.json();
console.log(state);

import requests

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

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

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:

{
  "version": "1.2.0",
  "uptime": 3600,
  "issues": []
}

Errors follow a consistent envelope:

{
  "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

State & Metrics

Read runtime state, metrics, transitions, models, and the live event stream.

Issues

Inspect one issue, abort work, override models, steer a run, or transition tracker state.

Attempts

Review run history and event timelines for past or current attempts.

Configuration

Read the effective config, inspect the schema, and manage overlay values.

Secrets

List, set, and delete encrypted runtime secrets.

Workspaces & Git

Inspect workspaces, clean them up, and read repository context.

What’s next

All Endpoints — browse the full surface area
Quickstart — start the local service before testing endpoints
Configuration Reference — understand the settings exposed through the API
Observability — use metrics and runtime signals in production

​At a glance

​Authentication

​Common first requests

​Response and error format

​Rate limits

​Endpoint groups

State & Metrics

Issues

Attempts

Configuration

Secrets

Workspaces & Git

​What’s next

At a glance

Authentication

Common first requests

Response and error format

Rate limits

Endpoint groups

What’s next