Skip to main content
Risoluto exposes a JSON REST API for orchestrator state, issue management, configuration, secrets, and real-time events. Every endpoint returns JSON unless otherwise noted (SSE, Prometheus text).
Interactive docs are available at /api/docs (Swagger UI) and the machine-readable spec at /api/v1/openapi.json.

​
Base URL

http://127.0.0.1:4000
The port is configurable via the --port CLI flag: 
risoluto --port 5000
All versioned endpoints live under /api/v1/. Prometheus metrics are at /metrics.

​
Authentication

ScenarioRequirement
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 via the RISOLUTO_WRITE_TOKEN environment variable: 
export RISOLUTO_WRITE_TOKEN="your-secret-token"
Loopback requests skip auth entirely, so local development and the dashboard work without a token.

​
Rate Limits

ScopeLimit
API endpoints (/api/*, /metrics)300 requests / minute per client
Webhooks (/webhooks/*)600 requests / minute per client
Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

​
Response Format

Successful responses return JSON with the relevant payload directly: 
{
  "version": "1.2.0",
  "uptime": 3600,
  "issues": []
}

​
Error Format

All errors follow a consistent envelope: 
{
  "error": "Issue not found",
  "status": 404
}

​
Quick Start

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

​
Endpoint Groups

State & Metrics

Orchestrator state, runtime info, Prometheus metrics, SSE events, and available models.

Issues

Issue detail, abort, model override, mid-turn steering, templates, and state transitions.

Attempts

List attempts per issue and inspect individual attempt timelines.

Configuration

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

Secrets

List, set, and delete runtime secrets without restarting.

Workspaces & Git

Workspace inventory, cleanup, and git repo context.
Last modified on March 31, 2026