# API reference

The complete, always-current surface is machine-readable:

- [`/openapi.json`](/openapi.json) — every endpoint, request and response shapes
- [`/llms.txt`](/llms.txt) — one-line orientation for agents
- [`/agents.md`](/agents.md) — operating instructions and the default loop
- [`/agent-setup/prompt.md`](/agent-setup/prompt.md) — required harness install, then the onboarding runbook in execution order
- [`/onboard.md`](/onboard.md) — backwards-compatible alias of the agent-setup prompt
- [`/skill.md`](/skill.md) — the loop procedure as an installable skill

## The endpoints you'll actually touch

| Endpoint | Auth | What |
|---|---|---|
| `POST /v1/provision` | none / own key | Idempotent project + keys (agents prefer this) |
| `POST /v1/signup` | none | Deprecated non-idempotent alias of provision (same terms) |
| `POST /v1/recover` | recovery code | Rotate lost keys |
| `POST /v1/traces` · `POST /v1/logs` · `POST /v1/metrics` | producer key | OTLP ingest, all three pillars (JSON or protobuf) |
| `POST /v1/feedback` · `/v1/feedback/audio` | feedback key | Typed / spoken user feedback |
| `GET /v1/ingest/health` | any project key | Setup status: last accepted / last rejected + reason |
| `GET /v1/telemetry` | agent key | Bounded record window; resolve ids from packets |
| `POST /v1/runs/diagnose` | agent key | The improvement packet over HTTP |
| `POST /v1/observations/open` · `/close` | agent key | Claim the window, then admit cited Issues with recommendations |
| `POST /v1/issues/decide` | agent key | Record an attributed Issue disposition; actor is self-reported on this key-only lane |
| `GET /v1/observations` | agent key | The observation ledger (open and decided) |
| `POST /v1/runs/replay` · `GET ?replay_id=` | agent key | Prove a prompt/model fix against captured failures pre-ship |
| `POST /v1/runs/eval-spec` | agent key | Executable eval spec your coding agent runs against real code |
| `POST /v1/evals` | producer or agent key | Record eval results — failed evals cluster like production failures |
| `GET /v1/loops` · `GET /v1/loops/<run_id>` | agent key | Loop history: runs, stages, verification |
| `POST /v1/loops/events` | agent key | Record grounded progress; verification outcomes are server-owned |
| `POST /v1/runs/verify` | agent key | Window-over-window verification |
| `GET/POST /v1/scoring` | agent key | Session-scorecard weights (reason required to change) |
| `GET/POST /v1/redaction` | agent key | [Data-scrubbing config](/docs/data-scrubbing) (reason required) |
| `POST /v1/projects/<id>/archive` | agent key | Stop ingest, downgrade keys — confirm with the project id |

Schemas: [`/schema/handoff-packet.json`](/schema/handoff-packet.json) ·
[`/schema/improvement-packet.json`](/schema/improvement-packet.json)

Everything here is also reachable as MCP tools from a
[connected agent](/docs/connect-your-coding-agent) — same operations, same
bounds, plus the loop's state machine.