Roadie sits between your application and the model providers (OpenAI, Anthropic, …). You bring your own provider keys (BYOK); Roadie gives you one unified API for chat and embeddings, plus everything a production AI backend needs: per-end-user identity and limits, quotas, spend budgets, usage metering, request logs, and streaming — without writing any of it yourself.

Node quickstart

Install the SDK, send your first chat, stream tokens, and create embeddings.

Next.js quickstart

Call Roadie from a server-side route with your secret key.

curl / REST quickstart

The raw HTTP contract — SSE streaming included.

Error reference

Every error type and code, with how to handle each.

​
How it fits together

There are two API surfaces (plan §21.1):
  • Data plane — /v1/…, served by the gateway. This is where your app sends POST /v1/chat and POST /v1/embeddings. Authenticated with a secret key (server) or a client token (browser / mobile).
  • Control plane — /v1/…, the management API behind the dashboard: projects, environments, API keys, provider credentials, limits, budgets, logs.
A request flows through the gateway pipeline: authenticate the key → apply key restrictions → resolve the model (alias → ordered targets, or a direct provider/model) → enforce rate limits, quotas, and budgets → call the provider with your BYOK credential (with retries and fallback) → meter usage and log the request. Every response carries an X-Request-Id, token usage, and an estimated cost.

​
The SDK

The @roadie/sdk TypeScript SDK is isomorphic (Node, browsers, React Native / Expo) with zero runtime dependencies. It wraps the data plane with typed errors, automatic retries, idempotency, timeouts, and streaming.
Roadie is pre-1.0 (0.x). The SDK and API may change while we gather feedback; changes inside /v1 are additive.

​
Every snippet here runs in CI

The TypeScript in these quickstarts is not illustrative. Each fenced block is a verbatim excerpt of a file under documentation/docs/snippets/ that is executed against a live gateway on every change, and a test asserts the page and the runnable file never drift. If a documented snippet stops compiling or stops working against the real wire contract, the build fails — so what you copy is what we test.