{ "openapi": "3.1.0", "info": { "title": "Roborama API", "version": "0.5.0", "summary": "Real robots as an API.", "description": "Statistically defensible evaluation of robot policies on physical hardware.\n\nDesign principles: every result carries `n` and a confidence interval (a bare percentage is a bug); everything is versioned (robots pin firmware, environments and suites pin revisions) so every result is reproducible and citable; the two meters (robot-hour × environment-hour) are visible in every quote; simulation is a first-class input (`verify` consumes sim-flagged scenarios and returns ground truth to recalibrate it).\n\nAuthentication: pass your API key (`rbr_live_` prefix) as a bearer token. The conventional environment variable is `ROBORAMA_API_KEY`.", "contact": { "name": "Roborama", "url": "https://roborama.com", "email": "api@roborama.com" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Roborama-ToS" } }, "servers": [ { "url": "https://api.roborama.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "runs", "description": "The core primitive. `POST /v1/runs` accepts a `kind` (`run | eval | verify | matrix | threshold | compare | transfer`) with kind-specific parameters mirroring the SDK." }, { "name": "robots", "description": "Embodiment discovery. Robots are addressed as `model@firmware`." }, { "name": "environments", "description": "Versioned catalogue scenes, from bare `cell-a` to `surgical-replica@v3`." }, { "name": "quote", "description": "Price a job before you run it. Both meters are visible in every quote." }, { "name": "suites", "description": "Frozen benchmark bundles: tasks + environments + perturbation schedules + scoring." }, { "name": "gates", "description": "CI gates: run a suite on matching refs, fail the check on regression." }, { "name": "streams", "description": "Live cell observability: WebRTC and MJPEG stream descriptors." }, { "name": "account", "description": "Usage, budgets, keys, and receipted data deletion." }, { "name": "calibration", "description": "Ground-truth calibration exports for simulator vendors (scoped license, validation use only)." }, { "name": "tasks", "description": "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." }, { "name": "kits", "description": "Object kits — customer hardware shipped to the facility, then tracked (mocap markers, mass, mesh scan) and made referenceable from Task Specs as `kit/`. Status: `received → tracked → available`." } ], "paths": { "/v1/runs": { "post": { "operationId": "createRun", "tags": [ "runs" ], "summary": "Create a run (any kind)", "description": "Creates a physical evaluation job. The `kind` field selects the primitive: `run` (default), `eval`, `verify`, `matrix`, `threshold`, `compare`, or `transfer`. Episode counts accept an integer or `auto(ci=…, moe=…)`, which sizes n for a target margin of error (Wilson interval). `max_budget_usd` is a hard stop, metered live.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreate" }, "examples": { "run": { "summary": "kind=run — the core primitive", "value": { "kind": "run", "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "policy": { "type": "container", "image": "ghcr.io/acme/skill:v4", "action_space": "joint_delta_50hz", "observation_contract": "droid-3cam" }, "task": "load_dishwasher@v2", "episodes": "auto(ci=0.95, moe=0.03)", "perturbation": { "layout_jitter_mm": 25, "lighting": [ "3000K", "5600K" ], "distractors": "set-B", "seed": 42 }, "data": { "retention": "30d", "train_on_failures": false }, "max_budget_usd": 4000 } }, "eval": { "summary": "kind=eval — versioned, citable suite", "value": { "kind": "eval", "policy": { "type": "checkpoint", "hf": "acme/skill-v4", "runtime": "openpi" }, "suite": "rbr-manip-core@v3", "robots": [ "g1-edu-pro@fw2.3" ], "publish": "private" } }, "verify": { "summary": "kind=verify — the interlock with simulation", "value": { "kind": "verify", "policy": { "type": "checkpoint", "hf": "acme/skill-v4", "runtime": "openpi" }, "scenarios": { "format": "layout-replay", "source": "sim_flagged_p1.json", "count": 318 }, "robots": [ "g1-edu-pro@fw2.3", "g1-edu-plus@fw2.3" ], "audit_sample": 0.1, "return_ground_truth": true } }, "matrix": { "summary": "kind=matrix — embodiments × environments", "value": { "kind": "matrix", "policy": { "type": "checkpoint", "hf": "acme/skill-v4", "runtime": "openpi" }, "robots": [ "g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4", "g1-edu-plus@fw2.3", "aloha2-pro@fw1.1", "spot-arm@fw4.1", "tiago-pro@fw2.0", "fr3-bench@fw5.2", "stretch3@fw1.9", "nori-a3@fw1.0", "so-101@fw1.2" ], "environments": [ "cell-a", "kitchen-std@v1.2", "warehouse-std@v2.0" ], "task": "pick_place_class3", "episodes_per_cell": "auto(ci=0.95, moe=0.05)" } }, "threshold": { "summary": "kind=threshold — the soak-to-verify outcome contract", "value": { "kind": "threshold", "policy_stream": { "webhook": "https://acme.ai/ckpt" }, "target": { "success_rate": 0.99, "ci": 0.95, "task": "bin_pick@v1" }, "iterate_on": "soak", "escalate_to": "g1-edu-pro@fw2.3", "monthly_cap_usd": 12000, "on_verified": { "webhook": "https://acme.ai/release-gate" } } }, "compare": { "summary": "kind=compare — paired A/B", "value": { "kind": "compare", "policies": { "v3": { "type": "checkpoint", "hf": "acme/skill-v3", "runtime": "openpi" }, "v4": { "type": "checkpoint", "hf": "acme/skill-v4", "runtime": "openpi" } }, "paired": true, "robot": "g1-edu-pro@fw2.3", "task": "shelf_restock@v1" } }, "transfer": { "summary": "kind=transfer — cross-embodiment gap", "value": { "kind": "transfer", "policy": { "type": "checkpoint", "hf": "acme/skill-v4", "runtime": "openpi" }, "source": "aloha-bimanual@fw3.1", "target": "g1-edu-pro@fw2.3", "task": "fold_towel@v2" } }, "matrix-espresso": { "summary": "Task-pinned matrix with interventions declared (espresso@v1)", "value": { "kind": "matrix", "task": "espresso@v1", "policy": { "type": "checkpoint", "hf": "pi/espresso-v7", "runtime": "openpi", "inference": { "action_horizon": 50, "chunk_size": 50, "temp": 0 }, "action_space": "joint_delta_50hz", "observation_contract": "droid-3cam" }, "robots": [ "g1-edu-pro@fw2.3", "g1-edu-pro@fw2.4", "g1-edu-plus@fw2.3", "stretch3@fw1.9" ], "environments": [ "kitchen-std@v1.2", "kitchen-replica@v2.0" ], "episodes_per_cell": "auto(ci=0.95, moe=0.05)", "interventions": "none" } } } } } }, "responses": { "201": { "description": "The created run, status `queued`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" }, "examples": { "queued": { "value": { "id": "run_8842", "object": "run", "kind": "run", "status": "queued", "created": "2026-08-28T14:02:11Z", "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "task": "load_dishwasher@v2", "episodes": "auto(ci=0.95, moe=0.03)", "priority": "standard", "max_budget_usd": 4000 } } } } } }, "402": { "$ref": "#/components/responses/BudgetError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "operationId": "listRuns", "tags": [ "runs" ], "summary": "List runs", "description": "Lists runs for the account, newest first.", "parameters": [ { "name": "kind", "in": "query", "schema": { "$ref": "#/components/schemas/RunKind" }, "description": "Filter by primitive kind." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "scheduling", "running", "completed", "failed", "stopped" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "A list of runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunList" }, "examples": { "list": { "value": { "object": "list", "url": "/v1/runs", "data": [ { "id": "run_8842", "object": "run", "kind": "run", "status": "completed", "created": "2026-08-28T14:02:11Z", "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "task": "load_dishwasher@v2", "result": { "n": 612, "success_rate": 0.874, "ci95": [ 0.846, 0.898 ], "interval_method": "wilson", "failure_clusters": { "grasp_slip": 41, "perception_miss": 22, "collision": 9 }, "robot_hours": 20.4, "environment_hours": 20.4, "cost_usd": 3812 } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/runs/{run_id}": { "get": { "operationId": "getRun", "tags": [ "runs" ], "summary": "Retrieve a run", "description": "Returns the run, its resolved pins (`@latest` is allowed on create, but the resolved pin is recorded), and — once completed — the result with n, rate, CI, failure clusters, both meters, and artifact links.", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" }, "examples": { "completed": { "value": { "id": "run_8842", "object": "run", "kind": "run", "status": "completed", "created": "2026-08-28T14:02:11Z", "completed": "2026-08-29T11:37:48Z", "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "task": "load_dishwasher@v2", "policy": { "type": "container", "image": "ghcr.io/acme/skill:v4", "action_space": "joint_delta_50hz", "observation_contract": "droid-3cam" }, "episodes": "auto(ci=0.95, moe=0.03)", "priority": "standard", "perturbation": { "layout_jitter_mm": 25, "lighting": [ "3000K", "5600K" ], "distractors": "set-B", "seed": 42 }, "data": { "retention": "30d", "train_on_failures": false }, "max_budget_usd": 4000, "resolved_pins": { "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "task": "load_dishwasher@v2", "perturbation_rev": "set-B@v1.4" }, "result": { "n": 612, "success_rate": 0.874, "ci95": [ 0.846, 0.898 ], "interval_method": "wilson", "failure_clusters": { "grasp_slip": 41, "perception_miss": 22, "collision": 9 }, "robot_hours": 20.4, "environment_hours": 20.4, "cost_usd": 3812, "artifacts": { "mcap": "https://api.roborama.com/v1/runs/run_8842/episodes?artifact=mcap", "video": "https://api.roborama.com/v1/runs/run_8842/episodes?artifact=video", "ground_truth": "https://api.roborama.com/v1/runs/run_8842/episodes?artifact=ground_truth", "report_pdf": "https://api.roborama.com/v1/runs/run_8842/report?format=pdf" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runs/{run_id}/episodes": { "get": { "operationId": "listEpisodes", "tags": [ "runs" ], "summary": "List episodes for a run", "description": "Every episode carries video, an MCAP recording (channels: `/joint_states_measured`, `/joint_targets_commanded`, `/camera/*`, `/ft_wrist`, `/gt/object_poses`, `/events`, `/meta`) and a replay spec — the initial conditions, re-runnable or sim-loadable. `/meta` carries reproducibility metadata: firmware, calibration age, actuator cycle counts, thermal state, seed, and realized (not just requested) perturbations.", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "name": "outcome", "in": "query", "schema": { "type": "string", "enum": [ "success", "failure" ] }, "description": "Filter by outcome." }, { "name": "cluster", "in": "query", "schema": { "type": "string" }, "description": "Filter failures by cluster, e.g. `grasp_slip`." } ], "responses": { "200": { "description": "A list of episodes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeList" }, "examples": { "episodes": { "value": { "object": "list", "url": "/v1/runs/run_8842/episodes", "data": [ { "id": "ep_17", "object": "episode", "index": 17, "outcome": "success", "duration_s": 118, "video_url": "https://artifacts.roborama.com/run_8842/ep_17/video.mp4", "mcap_url": "https://artifacts.roborama.com/run_8842/ep_17/episode.mcap", "replay_spec": { "environment": "kitchen-std@v1.2", "layout_seed": 42017, "lighting": "5600K", "distractors": "set-B" } } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runs/{run_id}/report": { "get": { "operationId": "getReport", "tags": [ "runs" ], "summary": "Retrieve the verification report", "description": "The deployment verification report: conformance evidence with n, rate, CI, failure clusters, resolved pins, and the perturbation schedule as realized. JSON by default; `format=pdf` returns the citable PDF.", "parameters": [ { "$ref": "#/components/parameters/RunId" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "pdf" ], "default": "json" } } ], "responses": { "200": { "description": "The report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" }, "examples": { "report": { "value": { "object": "report", "run_id": "run_8842", "kind": "verification", "result": { "n": 612, "success_rate": 0.874, "ci95": [ 0.846, 0.898 ], "interval_method": "wilson" }, "resolved_pins": { "robot": "g1-edu-pro@fw2.3", "environment": "kitchen-std@v1.2", "task": "load_dishwasher@v2", "perturbation_rev": "set-B@v1.4" }, "citation": "Roborama run run_8842, 2026-08-29, g1-edu-pro@fw2.3 × kitchen-std@v1.2", "pdf_url": "https://api.roborama.com/v1/runs/run_8842/report?format=pdf" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runs/{run_id}/export": { "post": { "operationId": "exportRun", "tags": [ "runs" ], "summary": "Export run data", "description": "Packages the run's episodes for training or analysis. Formats: `lerobot`, `rlds`, `mcap-bundle`. Respects the run's `data.train_on_failures` posture.", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "lerobot", "rlds", "mcap-bundle" ] } } }, "examples": { "lerobot": { "value": { "format": "lerobot" } } } } } }, "responses": { "202": { "description": "Export accepted; poll the returned object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" }, "examples": { "accepted": { "value": { "object": "export", "id": "exp_2214", "run_id": "run_8842", "format": "lerobot", "status": "preparing", "download_url": null } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runs/{run_id}/events": { "get": { "operationId": "watchRun", "tags": [ "runs" ], "summary": "Watch a run (server-sent events)", "description": "Live event stream: episode ticker, status transitions, and WebRTC stream URLs for the cell. Equivalent to `run.watch()` in the SDKs.", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "description": "An SSE stream of run events.", "content": { "text/event-stream": { "schema": { "type": "string" }, "examples": { "stream": { "summary": "Two events from a live run", "value": "event: episode\ndata: {\"episode\": 213, \"of\": 612, \"outcome\": \"success\", \"duration_s\": 121}\n\nevent: status\ndata: {\"status\": \"running\", \"cell\": \"cell-g1-04\", \"webrtc\": \"wss://streams.roborama.com/cells/cell-g1-04/webrtc\"}\n\n" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/robots": { "get": { "operationId": "listRobots", "tags": [ "robots" ], "summary": "List robots", "description": "Embodiments available in the facility, with pinned firmwares, cell counts, live duty cycle, and rate-card tier (`soak` commodity pods or `verify` verification-tier hardware).", "parameters": [ { "name": "class", "in": "query", "schema": { "type": "string", "enum": [ "humanoid", "quadruped-manip", "bimanual", "mobile-manipulator", "fixed-arm", "arm-pod" ] } }, { "name": "tier", "in": "query", "schema": { "type": "string", "enum": [ "soak", "verify" ] } } ], "responses": { "200": { "description": "A list of robots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RobotList" }, "examples": { "robots": { "value": { "object": "list", "url": "/v1/robots", "data": [ { "id": "g1-edu-pro", "class": "humanoid", "dof": 37, "hands": "dex3-1", "firmwares": [ "2.3", "2.4" ], "cells": 6, "duty_cycle_pct": 71, "tier": "verify" }, { "id": "nori-a3", "class": "arm-pod", "dof": 6, "hands": "gripper-2f", "firmwares": [ "1.0" ], "cells": 24, "duty_cycle_pct": 83, "tier": "soak" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/environments": { "get": { "operationId": "listEnvironments", "tags": [ "environments" ], "summary": "List environments", "description": "Versioned catalogue scenes. `adder_tier` (`bare | standard | replica | instrumented-replica`) maps to the environment-hour rate card.", "parameters": [ { "name": "cls", "in": "query", "schema": { "type": "string" }, "description": "Filter by scene class, e.g. `kitchen`." } ], "responses": { "200": { "description": "A list of environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentList" }, "examples": { "environments": { "value": { "object": "list", "url": "/v1/environments", "data": [ { "id": "kitchen-std", "rev": "v1.2", "class": "kitchen", "instrumentation": [ "mocap", "ft" ], "objects": 214, "reset": "scripted", "adder_tier": "replica" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/quote": { "post": { "operationId": "createQuote", "tags": [ "quote" ], "summary": "Quote a job", "description": "Prices a job before you run it. Both meters — robot-hours and environment-hours — are visible in every quote, with a queue ETA for the requested priority.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "humanoid600": { "summary": "600 humanoid episodes in the kitchen replica", "value": { "robot": "g1-edu-pro", "environment": "kitchen-std", "episodes": 600 } } } } } }, "responses": { "200": { "description": "The quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "examples": { "humanoid600": { "value": { "object": "quote", "robot": "g1-edu-pro", "environment": "kitchen-std", "episodes": 600, "priority": "standard", "robot_hours": 20, "env_hours": 20, "usd": 3740, "queue_eta": "6h", "breakdown": { "minutes_per_episode_est": 2, "robot_usd_per_hour": 148, "env_usd_per_hour": 39, "robot_usd": 2960, "env_usd": 780 }, "expires": "2026-09-08T00:00:00Z" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/suites": { "get": { "operationId": "listSuites", "tags": [ "suites" ], "summary": "List benchmark suites", "description": "Frozen bundles: tasks + environments + perturbation schedules + scoring. Results on the same suite revision are comparable across customers — this is what makes independent citation possible.", "responses": { "200": { "description": "A list of suites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuiteList" }, "examples": { "suites": { "value": { "object": "list", "url": "/v1/suites", "data": [ { "id": "rbr-manip-core", "rev": "v3", "frozen": "2026-03-14", "scoring": "binary success, Wilson 95% interval", "episodes_per_task": 300, "tasks": [ "pick_place@v1", "load_dishwasher@v2", "shelf_restock@v1", "fold_towel@v2", "bin_pick@v1" ], "environments": [ "kitchen-std@v1.2", "warehouse-std@v2.0", "cell-a@v1.0" ] } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/gates": { "post": { "operationId": "createGate", "tags": [ "gates" ], "summary": "Create a CI gate", "description": "Runs the suite on every ref matching `on` and fails the check when any `fail_if` condition trips. Pair with the `regression.detected` webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateCreate" }, "examples": { "release": { "value": { "on": "release/*", "suite": "rbr-manip-core@v3", "robots": [ "g1-edu-pro@fw2.3" ], "fail_if": { "success_rate_drop_pts": 2, "new_collision": true } } } } } } }, "responses": { "201": { "description": "The created gate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Gate" }, "examples": { "created": { "value": { "object": "gate", "id": "gate_312", "on": "release/*", "suite": "rbr-manip-core@v3", "robots": [ "g1-edu-pro@fw2.3" ], "fail_if": { "success_rate_drop_pts": 2, "new_collision": true }, "status": "active" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/streams/{cell}": { "get": { "operationId": "getStream", "tags": [ "streams" ], "summary": "Get a cell stream descriptor", "description": "WebRTC and MJPEG endpoints plus a short-lived viewer token for a live cell.", "parameters": [ { "name": "cell", "in": "path", "required": true, "schema": { "type": "string" }, "example": "cell-g1-04" } ], "responses": { "200": { "description": "The stream descriptor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stream" }, "examples": { "stream": { "value": { "object": "stream", "cell": "cell-g1-04", "webrtc": "wss://streams.roborama.com/cells/cell-g1-04/webrtc", "mjpeg": "https://streams.roborama.com/cells/cell-g1-04/mjpeg", "viewer_token": "vt_7Kq2mHentXw4", "expires": "2026-09-01T20:00:00Z" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "tags": [ "account" ], "summary": "Get usage for a period", "description": "Robot-hours by tier, environment-hours by class, and dollars, for the given billing period.", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "example": "2026-09" } ], "responses": { "200": { "description": "Usage for the period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "examples": { "september": { "value": { "object": "usage", "period": "2026-09", "robot_hours": { "verify": 141.2, "soak": 2210.5 }, "env_hours": { "bare": 96, "standard": 402.3, "replica": 118.9, "instrumented-replica": 6.2 }, "usd_total": 18940, "budget": { "monthly_usd": 25000, "hard": true, "remaining_usd": 6060 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/budgets": { "put": { "operationId": "setBudget", "tags": [ "account" ], "summary": "Set the monthly budget", "description": "With `hard: true`, new work is rejected and running work is stopped at the cap (`monthly_budget_exceeded`). Metered live.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" }, "examples": { "hardCap": { "value": { "monthly_usd": 25000, "hard": true } } } } } }, "responses": { "200": { "description": "The budget in force.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" }, "examples": { "hardCap": { "value": { "monthly_usd": 25000, "hard": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/keys": { "post": { "operationId": "createKey", "tags": [ "account" ], "summary": "Create an API key", "description": "Keys are scoped (e.g. `runs:write`, `streams:read`, `data:purge`). The secret (`rbr_live_` prefix) is shown once at creation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scope" ], "properties": { "scope": { "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" } } } }, "examples": { "ciKey": { "value": { "scope": [ "runs:write", "streams:read" ] } } } } } }, "responses": { "201": { "description": "The created key. `secret` is shown once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" }, "examples": { "created": { "value": { "object": "key", "id": "key_51ab", "scope": [ "runs:write", "streams:read" ], "secret": "rbr_live_4eC39HqLyjWDarjtT1zdp7dc", "created": "2026-09-01T12:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "operationId": "listKeys", "tags": [ "account" ], "summary": "List API keys", "description": "Lists keys for the account. Secrets are never returned after creation.", "responses": { "200": { "description": "A list of keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } } }, "examples": { "list": { "value": { "object": "list", "data": [ { "object": "key", "id": "key_51ab", "scope": [ "runs:write", "streams:read" ], "created": "2026-09-01T12:00:00Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/calibration/exports": { "post": { "operationId": "createCalibrationExport", "tags": [ "calibration" ], "summary": "Export calibration data", "description": "Ground-truth channels (`gt/object_poses`, `commanded_vs_executed`, `contact_events`) for simulator recalibration. Licensed under `sim-calibration-v1`: validation use, no policy training.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalibrationExportRequest" }, "examples": { "kitchen": { "value": { "embodiment": "g1-edu-pro", "scenes": [ "kitchen-std@v1.2" ], "channels": [ "gt/object_poses", "commanded_vs_executed", "contact_events" ], "license": "sim-calibration-v1" } } } } } }, "responses": { "202": { "description": "Export accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" }, "examples": { "accepted": { "value": { "object": "export", "id": "exp_9017", "format": "mcap-bundle", "status": "preparing", "download_url": null } } } } } }, "403": { "$ref": "#/components/responses/ScopeError" } } } }, "/v1/data/{run_id}": { "delete": { "operationId": "purgeData", "tags": [ "account" ], "summary": "Purge run data (receipted)", "description": "Customer-initiated deletion of all artifacts for a run. Returns a deletion receipt. Requires the `data:purge` scope.", "parameters": [ { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "description": "The deletion receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeReceipt" }, "examples": { "receipt": { "value": { "object": "purge_receipt", "id": "prg_77c2", "run_id": "run_8842", "status": "completed", "purged_at": "2026-09-01T13:14:00Z" } } } } } }, "403": { "$ref": "#/components/responses/ScopeError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tasks": { "post": { "operationId": "createTask", "tags": [ "tasks" ], "summary": "Create a Task Spec", "description": "Formalize a claim as a declarative, versioned Task Spec. Every success predicate is validated at creation against the instruments available in the target environment class; a predicate that binds to no instrument fails with `contract_validation_failed`. The new spec starts in `draft`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" }, "examples": { "espresso": { "summary": "The espresso claim as a Task Spec", "value": { "name": "espresso", "visibility": "private", "initial_conditions": { "machine": { "object": "kit/acme-breville", "pose": "P1", "tol_mm": 20 }, "cup": { "object": "catalogue/cup-std-08", "randomize": "zone-A" } }, "success_predicates": [ { "cup_on_tray": "gt.pose(cup) within tray_zone" }, { "liquid_mass": "scale.delta between 25 and 40 g" }, { "no_spill": "vision.spill_area < 2 cm2" }, { "t_complete": "episode.duration < 180 s" } ], "instructions": { "sampled_per_episode": [ "make an espresso", "brew me a coffee", "fais un espresso" ], "held_out": [ "prepare a single shot" ] }, "stages": [ { "grasp_cup": "gt.pose(cup) in gripper" }, { "cup_placed": "gt.pose(cup) within drip_zone" }, { "extraction": "scale.delta > 0 within 60s" }, { "served": "all success_predicates" } ], "envelope": { "lighting": [ "3000K", "5600K" ], "distractors": "set-B", "out_of_scope": [ "oat_milk" ] }, "baseline": { "internal_trials": 30, "internal_rate": 0.87 } } } } } } }, "responses": { "201": { "description": "The created Task Spec, status `draft` (compact form; GET /v1/tasks/{task_id} returns the full spec).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "value": { "id": "task_espresso_01", "object": "task", "name": "espresso", "rev": null, "status": "draft", "visibility": "private", "created": "2026-08-20T09:14:02Z", "frozen": null, "signatures": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "operationId": "listTasks", "tags": [ "tasks" ], "summary": "List Task Specs", "description": "All Task Specs visible to the key's account, drafts and frozen revisions alike.", "responses": { "200": { "description": "Task Spec list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskList" }, "examples": { "default": { "value": { "object": "list", "url": "/v1/tasks", "data": [ { "id": "task_espresso_01", "object": "task", "name": "espresso", "rev": "espresso@v1", "status": "frozen", "visibility": "private", "created": "2026-08-20T09:14:02Z", "frozen": "2026-08-24T16:40:11Z", "signatures": [ "acct_acme", "roborama" ], "initial_conditions": { "machine": { "object": "kit/acme-breville", "pose": "P1", "tol_mm": 20 }, "cup": { "object": "catalogue/cup-std-08", "randomize": "zone-A" } }, "success_predicates": [ { "cup_on_tray": "gt.pose(cup) within tray_zone" }, { "liquid_mass": "scale.delta between 22 and 42 g" }, { "no_spill": "vision.spill_area < 2 cm2" }, { "t_complete": "episode.duration < 180 s" } ], "instructions": { "sampled_per_episode": [ "make an espresso", "brew me a coffee", "fais un espresso" ], "held_out": [ "prepare a single shot" ] }, "stages": [ { "grasp_cup": "gt.pose(cup) in gripper" }, { "cup_placed": "gt.pose(cup) within drip_zone" }, { "extraction": "scale.delta > 0 within 60s" }, { "served": "all success_predicates" } ], "envelope": { "lighting": [ "3000K", "5600K" ], "distractors": "set-B", "out_of_scope": [ "oat_milk" ] }, "pilot": { "run_id": "run_9088", "robot": "g1-edu-pro@fw2.3", "episodes": 25, "amendments": 1 } } ], "has_more": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tasks/{task_id}": { "get": { "operationId": "getTask", "tags": [ "tasks" ], "summary": "Get a Task Spec", "description": "Fetch a Task Spec by id or by frozen revision (`espresso@v1`).", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task id (`task_espresso_01`) or frozen revision (`espresso@v1`)." } ], "responses": { "200": { "description": "The Task Spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "value": { "id": "task_espresso_01", "object": "task", "name": "espresso", "rev": "espresso@v1", "status": "frozen", "visibility": "private", "created": "2026-08-20T09:14:02Z", "frozen": "2026-08-24T16:40:11Z", "signatures": [ "acct_acme", "roborama" ], "initial_conditions": { "machine": { "object": "kit/acme-breville", "pose": "P1", "tol_mm": 20 }, "cup": { "object": "catalogue/cup-std-08", "randomize": "zone-A" } }, "success_predicates": [ { "cup_on_tray": "gt.pose(cup) within tray_zone" }, { "liquid_mass": "scale.delta between 22 and 42 g" }, { "no_spill": "vision.spill_area < 2 cm2" }, { "t_complete": "episode.duration < 180 s" } ], "instructions": { "sampled_per_episode": [ "make an espresso", "brew me a coffee", "fais un espresso" ], "held_out": [ "prepare a single shot" ] }, "stages": [ { "grasp_cup": "gt.pose(cup) in gripper" }, { "cup_placed": "gt.pose(cup) within drip_zone" }, { "extraction": "scale.delta > 0 within 60s" }, { "served": "all success_predicates" } ], "envelope": { "lighting": [ "3000K", "5600K" ], "distractors": "set-B", "out_of_scope": [ "oat_milk" ] }, "pilot": { "run_id": "run_9088", "robot": "g1-edu-pro@fw2.3", "episodes": 25, "amendments": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tasks/{task_id}/pilot": { "post": { "operationId": "pilotTask", "tags": [ "tasks" ], "summary": "Run a pilot (calibration session)", "description": "A small calibration session on the named robot. The customer watches live via `stream_url`; the session moves the spec from `draft` to `piloting`. Pilot episodes calibrate the method — they are not evidence and never appear in verification reports.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "robot" ], "properties": { "robot": { "type": "string", "examples": [ "g1-edu-pro@fw2.3" ] }, "episodes": { "type": "integer", "default": 25 } } }, "examples": { "default": { "value": { "robot": "g1-edu-pro@fw2.3", "episodes": 25 } } } } } }, "responses": { "200": { "description": "The pilot session handle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pilot" }, "examples": { "default": { "value": { "run_id": "run_9088", "robot": "g1-edu-pro@fw2.3", "episodes": 25, "stream_url": "wss://streams.roborama.com/cells/cell-g1-02/webrtc" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tasks/{task_id}/amend": { "post": { "operationId": "amendTask", "tags": [ "tasks" ], "summary": "Amend a draft or piloting Task Spec", "description": "Iterate on the method while piloting. Any TaskCreate field may be amended; amendments are rejected with `task_frozen` semantics once the spec is frozen (a frozen spec is immutable — create the next revision instead).", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Any TaskCreate field may be supplied; omitted fields are unchanged.", "properties": { "name": { "type": "string", "examples": [ "espresso" ] }, "visibility": { "type": "string", "enum": [ "private", "published" ], "default": "private", "description": "Private tasks stay the customer's method; published tasks join the public catalogue and become cross-customer comparable." }, "initial_conditions": { "type": "object", "description": "Named objects with poses, tolerances, and randomization zones. Kit hardware is referenced as `kit/`.", "additionalProperties": true }, "success_predicates": { "type": "array", "description": "Each predicate must bind to an available instrument in the target environment class; validated at creation.", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "instructions": { "type": "object", "description": "Instruction distribution for language-conditioned policies. Held-out paraphrases are never sampled during iteration and are reported separately.", "properties": { "sampled_per_episode": { "type": "array", "items": { "type": "string" } }, "held_out": { "type": "array", "items": { "type": "string" } } } }, "stages": { "type": "array", "description": "Ordered stage predicates; per-stage rates ship in results.", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "envelope": { "type": "object", "description": "The claim's declared boundaries. Out-of-scope declarations appear verbatim on reports.", "additionalProperties": true }, "baseline": { "type": "object", "description": "Customer's internal trials — used to sanity-check the pilot and set expectations, never published.", "properties": { "internal_trials": { "type": "integer" }, "internal_rate": { "type": "number" } } } }, "additionalProperties": false }, "examples": { "widen-liquid-mass": { "summary": "Widen the liquid_mass band after the pilot", "value": { "success_predicates": [ { "cup_on_tray": "gt.pose(cup) within tray_zone" }, { "liquid_mass": "scale.delta between 22 and 42 g" }, { "no_spill": "vision.spill_area < 2 cm2" }, { "t_complete": "episode.duration < 180 s" } ] } } } } } }, "responses": { "200": { "description": "The amended Task Spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "value": { "id": "task_espresso_01", "object": "task", "name": "espresso", "rev": null, "status": "piloting", "visibility": "private", "created": "2026-08-20T09:14:02Z", "frozen": null, "signatures": [], "pilot": { "run_id": "run_9088", "robot": "g1-edu-pro@fw2.3", "episodes": 25, "amendments": 1 }, "success_predicates": [ { "cup_on_tray": "gt.pose(cup) within tray_zone" }, { "liquid_mass": "scale.delta between 22 and 42 g" }, { "no_spill": "vision.spill_area < 2 cm2" }, { "t_complete": "episode.duration < 180 s" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/tasks/{task_id}/freeze": { "post": { "operationId": "freezeTask", "tags": [ "tasks" ], "summary": "Freeze the Task Spec", "description": "Freezes the current method as the next immutable revision (`espresso@v1`), mutually signed. Every verification report cites the frozen revision. Changes after a freeze create `@v2`; results across revisions are not silently comparable.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The frozen Task Spec.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "default": { "value": { "id": "task_espresso_01", "object": "task", "name": "espresso", "rev": "espresso@v1", "status": "frozen", "visibility": "private", "created": "2026-08-20T09:14:02Z", "frozen": "2026-08-24T16:40:11Z", "signatures": [ "acct_acme", "roborama" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/kits": { "post": { "operationId": "registerKit", "tags": [ "kits" ], "summary": "Register an object kit", "description": "Register customer hardware for inbound shipping. The response includes the shipping label URL; on arrival the kit is tracked (mocap markers, mass, mesh scan) and becomes referenceable from Task Specs as `kit/`. Kits integrate into the standard fixture/tracking/reset system — the system is never customized around a kit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KitCreate" }, "examples": { "default": { "value": { "name": "acme-breville", "items": [ { "desc": "Breville BES870", "qty": 1 } ] } } } } } }, "responses": { "201": { "description": "The registered kit, status `registered`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kit" }, "examples": { "default": { "value": { "id": "kit_acme_breville", "object": "kit", "name": "acme-breville", "status": "registered", "status_history": [ { "status": "registered", "at": "2026-08-12T10:02:00Z" } ], "items": [ { "desc": "Breville BES870", "qty": 1 } ], "tracking": null, "environment_ref": null, "shipping_label_url": "https://api.roborama.com/v1/kits/kit_acme_breville/shipping-label" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/kits/{kit_id}": { "get": { "operationId": "getKit", "tags": [ "kits" ], "summary": "Get a kit and its status progression", "description": "Status progresses `received → tracked → available`; `status_history` carries the timestamps.", "parameters": [ { "name": "kit_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The kit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kit" }, "examples": { "default": { "value": { "id": "kit_acme_breville", "object": "kit", "name": "acme-breville", "status": "available", "status_history": [ { "status": "registered", "at": "2026-08-12T10:02:00Z" }, { "status": "received", "at": "2026-08-15T18:30:00Z" }, { "status": "tracked", "at": "2026-08-17T09:12:00Z" }, { "status": "available", "at": "2026-08-17T14:45:00Z" } ], "items": [ { "desc": "Breville BES870", "qty": 1 } ], "tracking": { "mocap_markers": 6, "mass_g": 10480, "mesh_scan": true }, "environment_ref": "kit/acme-breville", "shipping_label_url": "https://api.roborama.com/v1/kits/kit_acme_breville/shipping-label" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/kits/{kit_id}/shipping-label": { "get": { "operationId": "getKitShippingLabel", "tags": [ "kits" ], "summary": "Get the inbound shipping label", "description": "A signed URL for the inbound shipping label PDF.", "parameters": [ { "name": "kit_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed label URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expires": { "type": "string", "format": "date-time" } } }, "examples": { "default": { "value": { "url": "https://artifacts.roborama.com/kits/kit_acme_breville/label.pdf?sig=8f31ab90", "expires": "2026-09-08T00:00:00Z" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "webhooks": { "run.completed": { "post": { "operationId": "webhookRunCompleted", "summary": "A run finished and its result is available", "description": "Sent when any run reaches `completed`. The payload carries the full result — n, rate, CI, clusters, both meters, cost.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "completed": { "value": { "id": "evt_3301", "type": "run.completed", "created": "2026-08-29T11:37:48Z", "data": { "run_id": "run_8842", "result": { "n": 612, "success_rate": 0.874, "ci95": [ 0.846, 0.898 ], "cost_usd": 3812 } } } } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "episode.failed": { "post": { "operationId": "webhookEpisodeFailed", "summary": "An episode failed, with its cluster", "description": "Sent per failed episode when subscribed. `cluster` names the failure mode, e.g. `grasp_slip`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "failed": { "value": { "id": "evt_3312", "type": "episode.failed", "created": "2026-08-28T16:11:02Z", "data": { "run_id": "run_8842", "episode": 214, "cluster": "grasp_slip", "video_url": "https://artifacts.roborama.com/run_8842/ep_214/video.mp4" } } } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "threshold.crossed": { "post": { "operationId": "webhookThresholdCrossed", "summary": "A threshold contract's target was met on soak tier", "description": "The contract escalates to the verification tier; `on_verified` fires after confirmation there.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "crossed": { "value": { "id": "evt_4407", "type": "threshold.crossed", "created": "2026-09-12T02:40:19Z", "data": { "contract_id": "run_9107", "checkpoint": "acme/skill-v4@ckpt-2210", "soak_result": { "n": 1188, "success_rate": 0.992, "ci95": [ 0.985, 0.995 ] }, "escalating_to": "g1-edu-pro@fw2.3" } } } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "regression.detected": { "post": { "operationId": "webhookRegressionDetected", "summary": "A gate or matrix found a regression vs. a prior run", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "regression": { "value": { "id": "evt_5150", "type": "regression.detected", "created": "2026-09-14T08:03:55Z", "data": { "run_id": "run_8901", "vs": "run_8821", "robot": "g1-edu-pro@fw2.4", "environment": "kitchen-std@v1.2", "delta_pts": -10.5, "cluster": "grasp_slip" } } } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "estop.triggered": { "post": { "operationId": "webhookEstopTriggered", "summary": "An emergency stop fired in a cell running your policy", "description": "The run is stopped, the episode is marked `estop`, and the cell is inspected before resuming. Partial results are kept.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "estop": { "value": { "id": "evt_6001", "type": "estop.triggered", "created": "2026-09-02T19:22:31Z", "data": { "run_id": "run_8905", "cell": "cell-g1-04", "episode": 88, "reason": "workspace_intrusion" } } } } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "API key with `rbr_live_` prefix, conventionally read from the `ROBORAMA_API_KEY` environment variable." } }, "parameters": { "RunId": { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "run_8842" } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "value": { "error": { "code": "invalid_api_key", "message": "Pass your API key as a bearer token: Authorization: Bearer $ROBORAMA_API_KEY.", "doc_url": "https://roborama.com/docs/errors/#invalid_api_key" } } } } } } }, "NotFound": { "description": "No such object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "value": { "error": { "code": "not_found", "message": "No run with id run_0000.", "doc_url": "https://roborama.com/docs/errors/#not_found" } } } } } } }, "ValidationError": { "description": "The request failed validation — including policy contract validation, which happens before any motor moves.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "contract": { "value": { "error": { "code": "contract_validation_failed", "message": "Policy declares action_space=joint_delta_50hz but g1-edu-pro@fw2.3 requires joint_delta_50hz with 37 joints; got 36.", "doc_url": "https://roborama.com/docs/errors/#contract_validation_failed" } } } } } } }, "BudgetError": { "description": "A budget hard stop fired. Partial results are kept.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "budget": { "value": { "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" } } } } } } }, "ScopeError": { "description": "The key lacks a required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "scope": { "value": { "error": { "code": "insufficient_scope", "message": "This key lacks the data:purge scope.", "doc_url": "https://roborama.com/docs/errors/#insufficient_scope" } } } } } } } }, "schemas": { "RunKind": { "type": "string", "enum": [ "run", "eval", "verify", "matrix", "threshold", "compare", "transfer" ], "description": "The primitive this run executes." }, "EpisodesSpec": { "description": "An integer episode count, or `auto(ci=…, moe=…)` which sizes n for a target margin of error at the given confidence (Wilson interval).", "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^auto\\(ci=0\\.[0-9]+, ?moe=0\\.[0-9]+\\)$" } ], "examples": [ 600, "auto(ci=0.95, moe=0.03)" ] }, "Policy": { "description": "Policy packaging. Declared contracts (`action_space`, `observation_contract`) are validated before any motor moves.", "oneOf": [ { "type": "object", "title": "Container", "required": [ "type", "image", "action_space", "observation_contract" ], "properties": { "type": { "const": "container" }, "image": { "type": "string", "examples": [ "ghcr.io/acme/skill:v4" ] }, "action_space": { "type": "string", "examples": [ "joint_delta_50hz", "joint_abs_20hz", "ee_pose_10hz" ] }, "observation_contract": { "type": "string", "examples": [ "droid-3cam" ] } } }, { "type": "object", "title": "Checkpoint", "required": [ "type", "hf", "runtime" ], "properties": { "type": { "const": "checkpoint" }, "hf": { "type": "string", "examples": [ "acme/skill-v4" ] }, "runtime": { "type": "string", "enum": [ "openpi", "lerobot" ] }, "inference": { "type": "object", "description": "Inference/decoding parameters, pinned and recorded — reproducibility includes decoding, not just weights.", "properties": { "action_horizon": { "type": "integer", "examples": [ 50 ] }, "chunk_size": { "type": "integer", "examples": [ 50 ] }, "temp": { "type": "number", "examples": [ 0 ] } } } } }, { "type": "object", "title": "Endpoint", "required": [ "type", "url" ], "properties": { "type": { "const": "endpoint" }, "url": { "type": "string", "format": "uri" }, "latency_budget_ms": { "type": "integer", "default": 80 }, "fallback": { "type": "string", "enum": [ "halt", "teleop" ], "default": "halt" } } } ] }, "Perturbation": { "type": "object", "description": "Seeded, versioned, replayable perturbation schedule. The schedule IS the product spec; realized perturbations are recorded in `/meta`.", "properties": { "layout_jitter_mm": { "type": "number" }, "lighting": { "type": "array", "items": { "type": "string" } }, "distractors": { "type": "string" }, "seed": { "type": "integer" } } }, "DataPosture": { "type": "object", "description": "Customer IP posture, explicit per run.", "properties": { "retention": { "type": "string", "examples": [ "30d", "90d", "0d" ] }, "train_on_failures": { "type": "boolean", "default": false, "description": "Customer IP boundary; contractual default false." } } }, "RunCreate": { "type": "object", "description": "Parameters for `POST /v1/runs`. `kind` selects the primitive; kind-specific fields mirror the SDK signatures.", "properties": { "kind": { "$ref": "#/components/schemas/RunKind", "default": "run" }, "robot": { "type": "string", "description": "`model@firmware`; `@latest` allowed, resolved pin recorded.", "examples": [ "g1-edu-pro@fw2.3" ] }, "robots": { "type": "array", "items": { "type": "string" }, "description": "For eval | verify | matrix." }, "environment": { "type": "string", "examples": [ "kitchen-std@v1.2" ] }, "environments": { "type": "array", "items": { "type": "string" }, "description": "For matrix." }, "policy": { "$ref": "#/components/schemas/Policy" }, "policies": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Policy" }, "description": "For compare: name → policy." }, "policy_stream": { "type": "object", "description": "For threshold: a webhook that receives checkpoint pushes.", "properties": { "webhook": { "type": "string", "format": "uri" } } }, "task": { "type": "string", "examples": [ "load_dishwasher@v2", "pick_place@v1" ] }, "suite": { "type": "string", "description": "For eval.", "examples": [ "rbr-manip-core@v3" ] }, "publish": { "type": "string", "enum": [ "private", "leaderboard" ], "default": "private", "description": "Leaderboard publication is opt-in only." }, "scenarios": { "type": "object", "description": "For verify: sim-flagged initial conditions (PolaRiS/Isaac/world-model formats or layout-replay specs)." }, "audit_sample": { "type": "number", "minimum": 0, "maximum": 1, "description": "For verify: fraction of random episodes run against the sim's blind spots." }, "return_ground_truth": { "type": "boolean", "description": "For verify: ship mocap 6-DoF poses + commanded-vs-executed, formatted to recalibrate your simulator." }, "source": { "type": "string", "description": "For transfer: embodiment the policy was trained on." }, "target": { "description": "For transfer: destination embodiment. For threshold: the target object.", "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "success_rate": { "type": "number" }, "ci": { "type": "number" }, "task": { "type": "string" } } } ] }, "iterate_on": { "type": "string", "description": "For threshold: commodity tier to iterate on.", "examples": [ "soak" ] }, "escalate_to": { "type": "string", "description": "For threshold: verification-tier embodiment for confirmation.", "examples": [ "g1-edu-pro@fw2.3" ] }, "monthly_cap_usd": { "type": "number", "description": "For threshold: hard monthly cap." }, "on_verified": { "type": "object", "properties": { "webhook": { "type": "string", "format": "uri" } } }, "paired": { "type": "boolean", "description": "For compare: same initial conditions per episode pair — halves the n needed to separate two policies." }, "episodes": { "$ref": "#/components/schemas/EpisodesSpec" }, "episodes_per_cell": { "$ref": "#/components/schemas/EpisodesSpec" }, "perturbation": { "$ref": "#/components/schemas/Perturbation" }, "data": { "$ref": "#/components/schemas/DataPosture" }, "priority": { "type": "string", "enum": [ "burst", "standard", "soak" ], "default": "standard", "description": "Maps to the rate-card priority tiers." }, "max_budget_usd": { "type": "number", "description": "Hard stop, metered live." }, "interventions": { "type": "string", "enum": [ "none", "on_stall", "scripted" ], "default": "none", "description": "Intervention policy, declared before the run. Counts and timestamps ship in results, and any intervened episode is flagged in the statistics." } } }, "Result": { "type": "object", "description": "Every result carries n and a confidence interval. Intervals are Wilson score intervals.", "required": [ "n", "success_rate", "ci95" ], "properties": { "n": { "type": "integer" }, "success_rate": { "type": "number" }, "ci95": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, "interval_method": { "type": "string", "const": "wilson" }, "failure_clusters": { "type": "object", "additionalProperties": { "type": "integer" } }, "robot_hours": { "type": "number", "description": "Displayed rounded to 0.1 h; billing uses exact minutes." }, "environment_hours": { "type": "number" }, "cost_usd": { "type": "number" }, "artifacts": { "type": "object", "properties": { "mcap": { "type": "string", "format": "uri" }, "video": { "type": "string", "format": "uri" }, "ground_truth": { "type": "string", "format": "uri" }, "report_pdf": { "type": "string", "format": "uri" } } }, "stage_rates": { "type": "array", "description": "Per-stage success rates with Wilson 95% intervals, for tasks whose spec declares stages. Present only on staged tasks.", "items": { "$ref": "#/components/schemas/StageRate" } }, "instruction_breakdown": { "type": "array", "description": "Success rate by instruction phrasing, held-out paraphrases reported separately. Present only when the task spec declares an instruction distribution.", "items": { "$ref": "#/components/schemas/InstructionRate" } }, "interventions": { "type": "object", "description": "Realized interventions against the declared policy. Any intervened episode is flagged in the statistics.", "properties": { "declared": { "type": "string", "enum": [ "none", "on_stall", "scripted" ] }, "count": { "type": "integer" }, "timestamps": { "type": "array", "items": { "type": "string", "format": "date-time" } } } } } }, "Run": { "type": "object", "required": [ "id", "object", "kind", "status" ], "properties": { "id": { "type": "string", "examples": [ "run_8842" ] }, "object": { "type": "string", "const": "run" }, "kind": { "$ref": "#/components/schemas/RunKind" }, "status": { "type": "string", "enum": [ "queued", "scheduling", "running", "completed", "failed", "stopped" ] }, "created": { "type": "string", "format": "date-time" }, "completed": { "type": "string", "format": "date-time" }, "robot": { "type": "string" }, "environment": { "type": "string" }, "task": { "type": "string" }, "policy": { "$ref": "#/components/schemas/Policy" }, "episodes": { "$ref": "#/components/schemas/EpisodesSpec" }, "priority": { "type": "string", "enum": [ "burst", "standard", "soak" ] }, "perturbation": { "$ref": "#/components/schemas/Perturbation" }, "data": { "$ref": "#/components/schemas/DataPosture" }, "max_budget_usd": { "type": "number" }, "resolved_pins": { "type": "object", "description": "Every version reference resolved at schedule time. `@latest` is allowed on create, but the resolved pin is recorded here.", "additionalProperties": { "type": "string" } }, "result": { "$ref": "#/components/schemas/Result" } } }, "RunList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } }, "Episode": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "episode" }, "index": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "success", "failure", "estop" ] }, "cluster": { "type": "string", "description": "Failure cluster, present when outcome=failure.", "examples": [ "grasp_slip" ] }, "duration_s": { "type": "number" }, "video_url": { "type": "string", "format": "uri" }, "mcap_url": { "type": "string", "format": "uri", "description": "Channels: /joint_states_measured, /joint_targets_commanded, /camera/*, /ft_wrist, /gt/object_poses (mocap), /events, /meta." }, "replay_spec": { "type": "object", "description": "Initial conditions, re-runnable or sim-loadable." } } }, "EpisodeList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Episode" } } } }, "Report": { "type": "object", "description": "The deployment verification report — conformance evidence, citable.", "properties": { "object": { "type": "string", "const": "report" }, "run_id": { "type": "string" }, "kind": { "type": "string", "const": "verification" }, "result": { "$ref": "#/components/schemas/Result" }, "resolved_pins": { "type": "object", "additionalProperties": { "type": "string" } }, "citation": { "type": "string" }, "pdf_url": { "type": "string", "format": "uri" } } }, "Export": { "type": "object", "properties": { "object": { "type": "string", "const": "export" }, "id": { "type": "string" }, "run_id": { "type": "string" }, "format": { "type": "string", "enum": [ "lerobot", "rlds", "mcap-bundle" ] }, "status": { "type": "string", "enum": [ "preparing", "ready", "expired" ] }, "download_url": { "type": [ "string", "null" ], "format": "uri" } } }, "Robot": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "g1-edu-pro" ] }, "class": { "type": "string", "enum": [ "humanoid", "bimanual", "mobile-manipulator", "arm-pod" ] }, "dof": { "type": "integer" }, "hands": { "type": "string", "examples": [ "dex3-1", "gripper-2f" ] }, "firmwares": { "type": "array", "items": { "type": "string" } }, "cells": { "type": "integer" }, "duty_cycle_pct": { "type": "number", "description": "Facility utilization metric (occupancy), not a success rate." }, "tier": { "type": "string", "enum": [ "soak", "verify" ] } } }, "RobotList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Robot" } } } }, "Environment": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "kitchen-std" ] }, "rev": { "type": "string", "examples": [ "v1.2" ] }, "class": { "type": "string", "examples": [ "kitchen" ] }, "instrumentation": { "type": "array", "items": { "type": "string", "enum": [ "mocap", "ft", "overhead-cam", "high-speed-cam" ] } }, "objects": { "type": "integer" }, "reset": { "type": "string", "enum": [ "scripted", "teleop-assisted" ] }, "adder_tier": { "type": "string", "enum": [ "bare", "standard", "replica", "instrumented-replica" ] } } }, "EnvironmentList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } } } }, "QuoteRequest": { "type": "object", "required": [ "robot", "environment", "episodes" ], "properties": { "robot": { "type": "string" }, "environment": { "type": "string" }, "episodes": { "$ref": "#/components/schemas/EpisodesSpec" }, "priority": { "type": "string", "enum": [ "burst", "standard", "soak" ], "default": "standard" } } }, "Quote": { "type": "object", "required": [ "robot_hours", "env_hours", "usd", "queue_eta" ], "properties": { "object": { "type": "string", "const": "quote" }, "robot": { "type": "string" }, "environment": { "type": "string" }, "episodes": { "$ref": "#/components/schemas/EpisodesSpec" }, "priority": { "type": "string" }, "robot_hours": { "type": "number" }, "env_hours": { "type": "number" }, "usd": { "type": "number" }, "queue_eta": { "type": "string", "examples": [ "6h" ] }, "breakdown": { "type": "object", "properties": { "minutes_per_episode_est": { "type": "number" }, "robot_usd_per_hour": { "type": "number" }, "env_usd_per_hour": { "type": "number" }, "robot_usd": { "type": "number" }, "env_usd": { "type": "number" } } }, "expires": { "type": "string", "format": "date-time" } } }, "Suite": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "rbr-manip-core" ] }, "rev": { "type": "string", "examples": [ "v3" ] }, "frozen": { "type": "string", "format": "date" }, "scoring": { "type": "string" }, "episodes_per_task": { "type": "integer" }, "tasks": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } } } }, "SuiteList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suite" } } } }, "GateCreate": { "type": "object", "required": [ "on", "suite", "robots", "fail_if" ], "properties": { "on": { "type": "string", "description": "Ref pattern, e.g. `release/*`." }, "suite": { "type": "string" }, "robots": { "type": "array", "items": { "type": "string" } }, "fail_if": { "type": "object", "properties": { "success_rate_drop_pts": { "type": "number" }, "new_collision": { "type": "boolean" } } } } }, "Gate": { "allOf": [ { "$ref": "#/components/schemas/GateCreate" }, { "type": "object", "properties": { "object": { "type": "string", "const": "gate" }, "id": { "type": "string", "examples": [ "gate_312" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] } } } ] }, "Stream": { "type": "object", "properties": { "object": { "type": "string", "const": "stream" }, "cell": { "type": "string" }, "webrtc": { "type": "string", "format": "uri" }, "mjpeg": { "type": "string", "format": "uri" }, "viewer_token": { "type": "string" }, "expires": { "type": "string", "format": "date-time" } } }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "const": "usage" }, "period": { "type": "string" }, "robot_hours": { "type": "object", "additionalProperties": { "type": "number" }, "description": "By tier: soak, verify." }, "env_hours": { "type": "object", "additionalProperties": { "type": "number" }, "description": "By adder tier: bare, standard, replica, instrumented-replica." }, "usd_total": { "type": "number" }, "budget": { "$ref": "#/components/schemas/Budget" } } }, "Budget": { "type": "object", "required": [ "monthly_usd" ], "properties": { "monthly_usd": { "type": "number" }, "hard": { "type": "boolean", "default": false, "description": "Hard stop: reject new work and stop running work at the cap." }, "remaining_usd": { "type": "number", "readOnly": true } } }, "KeyScope": { "type": "string", "enum": [ "runs:read", "runs:write", "streams:read", "data:purge", "keys:admin", "calibration:export" ] }, "Key": { "type": "object", "properties": { "object": { "type": "string", "const": "key" }, "id": { "type": "string" }, "scope": { "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" } }, "secret": { "type": "string", "description": "`rbr_live_` prefix. Shown once at creation, never again." }, "created": { "type": "string", "format": "date-time" } } }, "CalibrationExportRequest": { "type": "object", "required": [ "embodiment", "scenes", "channels", "license" ], "properties": { "embodiment": { "type": "string" }, "scenes": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "gt/object_poses", "commanded_vs_executed", "contact_events" ] } }, "license": { "type": "string", "const": "sim-calibration-v1", "description": "Scoped: validation use, no policy training." } } }, "PurgeReceipt": { "type": "object", "properties": { "object": { "type": "string", "const": "purge_receipt" }, "id": { "type": "string" }, "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "completed" ] }, "purged_at": { "type": "string", "format": "date-time" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created", "data" ], "properties": { "id": { "type": "string", "examples": [ "evt_3301" ] }, "type": { "type": "string", "enum": [ "run.completed", "episode.failed", "threshold.crossed", "regression.detected", "estop.triggered" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "insufficient_scope", "not_found", "contract_validation_failed", "firmware_pin_unavailable", "environment_unavailable", "task_unknown", "scenario_format_invalid", "episodes_invalid", "budget_exceeded", "monthly_budget_exceeded", "quote_expired", "queue_timeout", "policy_endpoint_timeout", "estop_triggered", "retention_expired", "publish_forbidden", "rate_limited" ] }, "message": { "type": "string" }, "run_id": { "type": "string" }, "doc_url": { "type": "string", "format": "uri", "description": "Every code is documented at /docs/errors/." } } } } }, "StageRate": { "type": "object", "required": [ "stage", "n", "success_rate", "ci95" ], "properties": { "stage": { "type": "string", "examples": [ "extraction" ] }, "n": { "type": "integer" }, "success_rate": { "type": "number" }, "ci95": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "InstructionRate": { "type": "object", "required": [ "instruction", "held_out", "n", "success_rate", "ci95" ], "properties": { "instruction": { "type": "string", "examples": [ "prepare a single shot" ] }, "held_out": { "type": "boolean" }, "n": { "type": "integer" }, "success_rate": { "type": "number" }, "ci95": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } }, "TaskCreate": { "type": "object", "required": [ "name", "initial_conditions", "success_predicates" ], "properties": { "name": { "type": "string", "examples": [ "espresso" ] }, "visibility": { "type": "string", "enum": [ "private", "published" ], "default": "private", "description": "Private tasks stay the customer's method; published tasks join the public catalogue and become cross-customer comparable." }, "initial_conditions": { "type": "object", "description": "Named objects with poses, tolerances, and randomization zones. Kit hardware is referenced as `kit/`.", "additionalProperties": true }, "success_predicates": { "type": "array", "description": "Each predicate must bind to an available instrument in the target environment class; validated at creation.", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "instructions": { "type": "object", "description": "Instruction distribution for language-conditioned policies. Held-out paraphrases are never sampled during iteration and are reported separately.", "properties": { "sampled_per_episode": { "type": "array", "items": { "type": "string" } }, "held_out": { "type": "array", "items": { "type": "string" } } } }, "stages": { "type": "array", "description": "Ordered stage predicates; per-stage rates ship in results.", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "envelope": { "type": "object", "description": "The claim's declared boundaries. Out-of-scope declarations appear verbatim on reports.", "additionalProperties": true }, "baseline": { "type": "object", "description": "Customer's internal trials — used to sanity-check the pilot and set expectations, never published.", "properties": { "internal_trials": { "type": "integer" }, "internal_rate": { "type": "number" } } } } }, "Task": { "type": "object", "required": [ "id", "object", "name", "status", "visibility" ], "properties": { "id": { "type": "string", "examples": [ "task_espresso_01" ] }, "object": { "const": "task" }, "name": { "type": "string" }, "rev": { "type": [ "string", "null" ], "description": "Frozen revision id, e.g. `espresso@v1`; null until frozen.", "examples": [ "espresso@v1" ] }, "status": { "type": "string", "enum": [ "draft", "piloting", "frozen" ] }, "visibility": { "type": "string", "enum": [ "private", "published" ] }, "created": { "type": "string", "format": "date-time" }, "frozen": { "type": [ "string", "null" ], "format": "date-time" }, "signatures": { "type": "array", "description": "Both parties sign the freeze; reports cite the signed revision.", "items": { "type": "string" } }, "initial_conditions": { "type": "object", "additionalProperties": true }, "success_predicates": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "instructions": { "type": "object", "additionalProperties": true }, "stages": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "envelope": { "type": "object", "additionalProperties": true }, "pilot": { "type": [ "object", "null" ], "description": "Latest pilot session, if any.", "properties": { "run_id": { "type": "string" }, "robot": { "type": "string" }, "episodes": { "type": "integer" }, "amendments": { "type": "integer" } } } } }, "TaskList": { "type": "object", "required": [ "object", "data" ], "properties": { "object": { "const": "list" }, "url": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "has_more": { "type": "boolean" } } }, "Pilot": { "type": "object", "required": [ "run_id", "stream_url" ], "properties": { "run_id": { "type": "string", "examples": [ "run_9088" ] }, "robot": { "type": "string" }, "episodes": { "type": "integer" }, "stream_url": { "type": "string", "description": "Live WebRTC stream — the customer watches the calibration session.", "examples": [ "wss://streams.roborama.com/cells/cell-g1-02/webrtc" ] } } }, "KitCreate": { "type": "object", "required": [ "name", "items" ], "properties": { "name": { "type": "string", "examples": [ "acme-breville" ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "desc", "qty" ], "properties": { "desc": { "type": "string" }, "qty": { "type": "integer" } } } } } }, "Kit": { "type": "object", "required": [ "id", "object", "name", "status" ], "properties": { "id": { "type": "string", "examples": [ "kit_acme_breville" ] }, "object": { "const": "kit" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "registered", "received", "tracked", "available" ], "description": "received → tracked (mocap markers, mass, mesh scan) → available as `kit/` in environments." }, "status_history": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "desc": { "type": "string" }, "qty": { "type": "integer" } } } }, "tracking": { "type": [ "object", "null" ], "properties": { "mocap_markers": { "type": "integer" }, "mass_g": { "type": "integer" }, "mesh_scan": { "type": "boolean" } } }, "environment_ref": { "type": [ "string", "null" ], "description": "How Task Specs reference the kit once available.", "examples": [ "kit/acme-breville" ] }, "shipping_label_url": { "type": "string" } } } } } }