# API reference

Generated from [/openapi.json](https://roborama.com/openapi.json) (OpenAPI 3.1). Base URL `https://api.roborama.com`, auth `Authorization: Bearer $ROBORAMA_API_KEY`.

```text
task (draft→pilot→frozen) → quote → run|eval|verify|matrix|threshold
                                → episodes (MCAP + video + GT)
                                        → result (n, rate, CI, clusters)
                                        → report (verification, citable)
                                        → webhook (gate your release)
```

## Runs

The core primitive. `POST /v1/runs` accepts a `kind` (`run | eval | verify | matrix | threshold | compare | transfer`) with kind-specific parameters mirroring the SDK.

- `POST /v1/runs` — Create a run (any kind) ([details](https://roborama.com/docs/api-reference/runs.md))
- `GET /v1/runs` — List runs ([details](https://roborama.com/docs/api-reference/runs.md))
- `GET /v1/runs/{run_id}` — Retrieve a run ([details](https://roborama.com/docs/api-reference/runs.md))
- `GET /v1/runs/{run_id}/episodes` — List episodes for a run ([details](https://roborama.com/docs/api-reference/runs.md))
- `GET /v1/runs/{run_id}/report` — Retrieve the verification report ([details](https://roborama.com/docs/api-reference/runs.md))
- `POST /v1/runs/{run_id}/export` — Export run data ([details](https://roborama.com/docs/api-reference/runs.md))
- `GET /v1/runs/{run_id}/events` — Watch a run (server-sent events) ([details](https://roborama.com/docs/api-reference/runs.md))

## Robots

Embodiment discovery. Robots are addressed as `model@firmware`.

- `GET /v1/robots` — List robots ([details](https://roborama.com/docs/api-reference/robots.md))

## Environments

Versioned catalogue scenes, from bare `cell-a` to `surgical-replica@v3`.

- `GET /v1/environments` — List environments ([details](https://roborama.com/docs/api-reference/environments.md))

## Quote

Price a job before you run it. Both meters are visible in every quote.

- `POST /v1/quote` — Quote a job ([details](https://roborama.com/docs/api-reference/quote.md))

## Suites

Frozen benchmark bundles: tasks + environments + perturbation schedules + scoring.

- `GET /v1/suites` — List benchmark suites ([details](https://roborama.com/docs/api-reference/suites.md))

## Gates

CI gates: run a suite on matching refs, fail the check on regression.

- `POST /v1/gates` — Create a CI gate ([details](https://roborama.com/docs/api-reference/gates.md))

## Streams

Live cell observability: WebRTC and MJPEG stream descriptors.

- `GET /v1/streams/{cell}` — Get a cell stream descriptor ([details](https://roborama.com/docs/api-reference/streams.md))

## Account

Usage, budgets, keys, and receipted data deletion.

- `GET /v1/usage` — Get usage for a period ([details](https://roborama.com/docs/api-reference/account.md))
- `PUT /v1/budgets` — Set the monthly budget ([details](https://roborama.com/docs/api-reference/account.md))
- `POST /v1/keys` — Create an API key ([details](https://roborama.com/docs/api-reference/account.md))
- `GET /v1/keys` — List API keys ([details](https://roborama.com/docs/api-reference/account.md))
- `DELETE /v1/data/{run_id}` — Purge run data (receipted) ([details](https://roborama.com/docs/api-reference/account.md))

## Calibration

Ground-truth calibration exports for simulator vendors (scoped license, validation use only).

- `POST /v1/calibration/exports` — Export calibration data ([details](https://roborama.com/docs/api-reference/calibration.md))

## Tasks

Task Specs — a customer claim formalized as a declarative, versioned protocol with instrument-bound success predicates. Lifecycle: `draft → piloting → frozen@vN`. Frozen specs are immutable; changes create the next revision.

- `POST /v1/tasks` — Create a Task Spec ([details](https://roborama.com/docs/api-reference/tasks.md))
- `GET /v1/tasks` — List Task Specs ([details](https://roborama.com/docs/api-reference/tasks.md))
- `GET /v1/tasks/{task_id}` — Get a Task Spec ([details](https://roborama.com/docs/api-reference/tasks.md))
- `POST /v1/tasks/{task_id}/pilot` — Run a pilot (calibration session) ([details](https://roborama.com/docs/api-reference/tasks.md))
- `POST /v1/tasks/{task_id}/amend` — Amend a draft or piloting Task Spec ([details](https://roborama.com/docs/api-reference/tasks.md))
- `POST /v1/tasks/{task_id}/freeze` — Freeze the Task Spec ([details](https://roborama.com/docs/api-reference/tasks.md))

## Kits

Object kits — customer hardware shipped to the facility, then tracked (mocap markers, mass, mesh scan) and made referenceable from Task Specs as `kit/<name>`. Status: `received → tracked → available`.

- `POST /v1/kits` — Register an object kit ([details](https://roborama.com/docs/api-reference/kits.md))
- `GET /v1/kits/{kit_id}` — Get a kit and its status progression ([details](https://roborama.com/docs/api-reference/kits.md))
- `GET /v1/kits/{kit_id}/shipping-label` — Get the inbound shipping label ([details](https://roborama.com/docs/api-reference/kits.md))

## Webhooks

Events delivered to your endpoint as signed POST requests: `run.completed`, `episode.failed`, `threshold.crossed`, `regression.detected`, `estop.triggered`. Acknowledge with any 2xx.

- `run.completed` — A run finished and its result is available ([details](https://roborama.com/docs/api-reference/webhooks.md))
- `episode.failed` — An episode failed, with its cluster ([details](https://roborama.com/docs/api-reference/webhooks.md))
- `threshold.crossed` — A threshold contract's target was met on soak tier ([details](https://roborama.com/docs/api-reference/webhooks.md))
- `regression.detected` — A gate or matrix found a regression vs. a prior run ([details](https://roborama.com/docs/api-reference/webhooks.md))
- `estop.triggered` — An emergency stop fired in a cell running your policy ([details](https://roborama.com/docs/api-reference/webhooks.md))