API reference
Generated from openapi.json: every endpoint, parameter, and example.
Generated from /openapi.json (OpenAPI 3.1) — the same file agents consume. Every operation ships with examples. Base URL: https://api.roborama.com, authenticated with Authorization: Bearer $ROBORAMA_API_KEY.
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.
| Endpoint | Summary |
|---|---|
POST /v1/runs | Create a run (any kind) |
GET /v1/runs | List runs |
GET /v1/runs/{run_id} | Retrieve a run |
GET /v1/runs/{run_id}/episodes | List episodes for a run |
GET /v1/runs/{run_id}/report | Retrieve the verification report |
POST /v1/runs/{run_id}/export | Export run data |
GET /v1/runs/{run_id}/events | Watch a run (server-sent events) |
Robots
Embodiment discovery. Robots are addressed as model@firmware.
| Endpoint | Summary |
|---|---|
GET /v1/robots | List robots |
Environments
Versioned catalogue scenes, from bare cell-a to surgical-replica@v3.
| Endpoint | Summary |
|---|---|
GET /v1/environments | List environments |
Quote
Price a job before you run it. Both meters are visible in every quote.
| Endpoint | Summary |
|---|---|
POST /v1/quote | Quote a job |
Suites
Frozen benchmark bundles: tasks + environments + perturbation schedules + scoring.
| Endpoint | Summary |
|---|---|
GET /v1/suites | List benchmark suites |
Gates
CI gates: run a suite on matching refs, fail the check on regression.
| Endpoint | Summary |
|---|---|
POST /v1/gates | Create a CI gate |
Streams
Live cell observability: WebRTC and MJPEG stream descriptors.
| Endpoint | Summary |
|---|---|
GET /v1/streams/{cell} | Get a cell stream descriptor |
Account
Usage, budgets, keys, and receipted data deletion.
| Endpoint | Summary |
|---|---|
GET /v1/usage | Get usage for a period |
PUT /v1/budgets | Set the monthly budget |
POST /v1/keys | Create an API key |
GET /v1/keys | List API keys |
DELETE /v1/data/{run_id} | Purge run data (receipted) |
Calibration
Ground-truth calibration exports for simulator vendors (scoped license, validation use only).
| Endpoint | Summary |
|---|---|
POST /v1/calibration/exports | Export calibration data |
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.
| Endpoint | Summary |
|---|---|
POST /v1/tasks | Create a Task Spec |
GET /v1/tasks | List Task Specs |
GET /v1/tasks/{task_id} | Get a Task Spec |
POST /v1/tasks/{task_id}/pilot | Run a pilot (calibration session) |
POST /v1/tasks/{task_id}/amend | Amend a draft or piloting Task Spec |
POST /v1/tasks/{task_id}/freeze | Freeze the Task Spec |
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.
| Endpoint | Summary |
|---|---|
POST /v1/kits | Register an object kit |
GET /v1/kits/{kit_id} | Get a kit and its status progression |
GET /v1/kits/{kit_id}/shipping-label | Get the inbound shipping label |
Webhooks
Events delivered to your endpoint as signed POST requests: run.completed, episode.failed, threshold.crossed, regression.detected, estop.triggered. Acknowledge with any 2xx.
| Event | Summary |
|---|---|
run.completed | A run finished and its result is available |
episode.failed | An episode failed, with its cluster |
threshold.crossed | A threshold contract's target was met on soak tier |
regression.detected | A gate or matrix found a regression vs. a prior run |
estop.triggered | An emergency stop fired in a cell running your policy |