Roadie exposes two REST surfaces (plan §21.1). Both use JSON bodies, cursor pagination, the uniform error envelope, an X-Request-Id on every response, and URL-major versioning (/v1) with additive-only changes inside a major.

​
Data plane —

The AI gateway. This is what your app calls at runtime:
  • POST /v1/chat — unified chat completions (streaming or not)
  • POST /v1/embeddings — unified embeddings
  • GET /v1/models — the models this key may use
  • POST /v1/requests/{request_id}/cancel — best-effort cancel of an in-flight request
The same gateway host also serves an OpenAI-compatible surface under /openai/v1/* (chat completions, embeddings, models, and images) for drop-in use with OpenAI SDKs — see the OpenAI-compatible reference.
Image generation and editing are available only on the OpenAI-compatible surface (/openai/v1/images/*). There is no native /v1/images endpoint on the data plane.
Authenticated with a secret key (server) or a client token (client apps).

​
Control plane —

The management API behind the dashboard: organizations, projects, environments, API keys, provider credentials, limits, budgets, end users, usage, and logs. Authenticated with your dashboard session or a management key (rd_mk_…). See the control-plane reference.

​
How the OpenAPI spec is generated

The control-plane API defines every route with a Zod schema, and generates an OpenAPI 3.1 document from those schemas at GET /openapi.json (served in every non-production environment). It is exported into this docs site by a script:
The script boots the api against a self-contained local stack (in-memory database + Redis, no external services), fetches /openapi.json, validates it, and writes the file that the control-plane reference renders. Regenerate it whenever a control-plane route or schema changes.

​
The data-plane gap

The gateway (data plane) does not emit an OpenAPI document today — it has no @fastify/swagger registration. Its endpoints (/v1/chat, /v1/embeddings, /v1/models) are therefore documented by hand in this section, with request/response examples that match the real wire shapes. Generating a gateway-side OpenAPI spec is a future work item; until then, these pages are the source of truth for the data plane.