REST

Bearer auth, JSON in and out, SSE for live events — every SDK call is one of these HTTP calls underneath.

The base URL is https://api.roborama.com. Authenticate with Authorization: Bearer $ROBORAMA_API_KEY; send Content-Type: application/json on anything with a body. Keys carry the rbr_live_ prefix, and a missing or invalid key is a 401 with code invalid_api_key. Every example on this page is a real request you can paste — the cURL tab on every example on this site is built the same way.

create a run

import roborama  # reads ROBORAMA_API_KEY from the environment

run = roborama.run(
    robot="g1-edu-pro@fw2.3",
    environment="kitchen-std@v1.2",
    task="pick_place@v1",
    episodes="auto(ci=0.95, moe=0.03)",
)
print(run.result())  # n=612  rate=0.874  ci95=(0.846, 0.898)

One endpoint, seven primitives

POST /v1/runs creates every kind of job. The kind field selects the primitive — run (the default), eval, verify, matrix, threshold, compare, or transfer — and the rest of the body is that primitive's fields, as documented from run() onward. The response is a run object whose status moves through queued, scheduling, and running to completed, failed, or stopped. Success rates in responses always arrive with n and ci95 attached; the API does not emit a bare percentage.

The endpoints

List endpoints take kind, status, and limit query parameters — GET /v1/runs?kind=eval is how CI polls for suite verdicts.

Method and path	Returns
`POST /v1/runs`	the created run; `kind` selects the primitive
`GET /v1/runs/{run_id}`	the run, its resolved pins, and once completed the result: `n`, `success_rate`, `ci95`, clusters, both meters
`GET /v1/runs/{run_id}/episodes`	per-episode artifacts: video, MCAP, replay spec
`GET /v1/runs/{run_id}/report`	the verification report (`format=pdf`)
`GET /v1/runs/{run_id}/events`	live server-sent events — use `curl -N`
`POST /v1/quote`	both meters, dollars, and `queue_eta` before you commit
`GET /v1/robots`	the catalogue: firmware pins, cells, duty cycle, tier
`GET /v1/environments`	the catalogue: revisions, instrumentation, reset class

Watch a run live

The events endpoint is the wire form of run.watch() in the SDKs: an episode ticker plus status transitions carrying the cell's WebRTC URL, delivered as they happen, with no polling interval to tune.

watch via SSE

import roborama  # reads ROBORAMA_API_KEY from the environment

run = roborama.runs.get("run_8842")

for event in run.watch():   # live: episode ticker + WebRTC stream URLs
    print(event.episode, event.status)

stream = roborama.streams.get("cell-g1-04")
print(stream)
# {webrtc: "wss://streams.roborama.com/cells/cell-g1-04/webrtc",
#  mjpeg: "https://streams.roborama.com/cells/cell-g1-04/mjpeg",
#  viewer_token: "vt_7Kq2mHentXw4"}

event: episode
data: {"episode": 213, "of": 612, "outcome": "success", "duration_s": 121}

event: status
data: {"status": "running", "cell": "cell-g1-04", "webrtc": "wss://streams.roborama.com/cells/cell-g1-04/webrtc"}

Errors

One envelope everywhere. code comes from the fixed set in the error reference, and doc_url points at the matching entry, so an error response is never a dead end:

{
  "error": {
    "code": "budget_exceeded",
    "message": "max_budget_usd=500 reached after 81 episodes; run stopped, partial result kept.",
    "run_id": "run_8907",
    "doc_url": "https://roborama.com/docs/errors/#budget_exceeded"
  }
}

The generated reference

The API reference is generated from /openapi.json — OpenAPI 3.1, with request and response examples on every operation. If you are generating a client or handing tools to an agent, consume the raw file; it is the same source these pages are checked against. See also the agent surface.

Getting started

Concepts

Primitives

API reference

SDKs

Guides

Reference