API reference

HTTP control plane — auth, idempotency, error envelope, and the live OpenAPI spec.

The Roboflare API is a single Cloudflare Worker speaking JSON over HTTPS. The full machine-readable spec lives at /openapi.json and an interactive Scalar reference is hosted at /docs on the same Worker.

This page documents the cross-cutting rules. For per-route schemas, use the OpenAPI document.

Base URL

https://api.roboflare.com

Override via the baseUrl constructor argument in the TypeScript SDK, the base_url field in ~/.config/roboflare/credentials.toml for the CLI, or the Client(base_url=...) argument in the Python SDK.

Authentication

Every request carries a portal token in the Authorization header:

Authorization: Bearer rf_org_...

Token formats:

rf_org_<hex> — bootstrap admin token issued at org approval.
rf_user_<hex> — per-user token issued through the dashboard's user management page.

Admin-only endpoints (/api/admin/*) additionally require the ROBOFLARE_ADMIN_TOKEN env var to be set on the Worker; if unset in local dev, admin routes return early in "dev-open" mode for ergonomics. Production deploys always set the env var.

Response envelope

List endpoints:

{ "items": [ ... ] }

Single-object endpoints:

{ "data": { ... } }

Errors:

{ "error": { "code": "not_found", "message": "release not found" } }

Common code values: bad_request, unauthorized, forbidden, not_found, conflict, http_error, internal_server_error.

Idempotency

POST /api/deployments and POST /api/configs/deployments require an Idempotency-Key header. Replay with the same key returns the original response instead of creating a duplicate row. The TypeScript and Python SDKs generate UUIDs for you; the CLI does the same.

Headers we set

X-Roboflare-Org-Id — the org context the request resolved to. Useful when debugging multi-org tokens.

WebSocket endpoints

Live streams are not in the OpenAPI document. Connect with the bearer token as a ?token= query parameter:

Endpoint	Frames
`/api/robots/{id}/logs/ws`	JSON log records
`/api/robots/{id}/shell/ws`	PTY bytes
`/api/robots/{id}/camera/ws`	Binary JPEG
`/api/robots/{id}/ros/topics/echo`	ROS topic echo

These bypass the Hono OpenAPI router and are served directly by the Cloudflare Worker entry point.

Spec-driven tooling

The TypeScript SDK is generated from packages/api-spec/openapi.json. If you're building your own client, point your OpenAPI generator (openapi-typescript, openapi-python-client, progenitor) at the hosted /openapi.json instead of vendoring the spec — it stays in lock step with the deployed API.