Control-Plane OpenAPI Schema and API Reference

The rolter control plane describes itself. GET /openapi.json returns an OpenAPI 3.1 document covering its whole management API — tenancy, users and RBAC, providers, routes, virtual keys, budgets and prices, guardrails, MCP, alerting, SSO, SCIM and the deployment settings the gateway reads back through /internal/snapshot. GET /docs renders the same document as an interactive reference you can read and try calls from in a browser.

This is the same pair the gateway serves for its OpenAI/Anthropic-compatible surface, so a deployment has two schemas: one for the traffic your applications send, and one for the API your tooling manages the deployment with.

Fetching the schema#

curl -s http://<your-control-plane-host>:4001/openapi.json > rolter-control.json

Both endpoints are unauthenticated. The document names endpoints and payload shapes and carries no tenant data, and a client that cannot read the schema before it holds a credential cannot generate against it either.

The info.version field tracks the running binary’s version, so a schema fetched from a live control plane always matches what that process serves.

Browsing it#

Open http://<your-control-plane-host>:4001/docs. The reference is rendered by Scalar from a JavaScript bundle embedded in the rolter binary — it makes no requests to a CDN, loads no remote fonts, and works in an air-gapped deployment, exactly like the gateway’s /docs.

Operations are grouped by tag: tenancy, users, access-control, providers, routes, virtual-keys, governance, guardrails, mcp, alerting, analytics, settings, sso, scim and the rest.

Generating a client#

Any OpenAPI generator works. For example, with openapi-generator:

openapi-generator generate \  -i http://localhost:4001/openapi.json \  -g python \  -o ./rolter-control-client

Authentication#

Every operation except the probes, the schema endpoints, the login and SSO routes and the invitation-acceptance links takes a bearer token:

Authorization: Bearer <token>

The token is a session token from POST /api/v1/auth/login, or the deployment admin token. /scim/v2/* takes a SCIM token instead, and /internal/* takes the internal token — the document declares one bearerAuth scheme covering all of them, because they occupy the same header.

Authorization is enforced per handler against the RBAC capability matrix, which GET /api/v1/rbac/matrix publishes: holding a valid token is not the same as being allowed to make a given call.

What the schema does and does not promise#

Request and response bodies are typed where the underlying handler has a stable shape — organizations, teams, projects, business units and customers, users and memberships, providers and provider groups, routes and route targets, virtual keys, budgets, rate limits and model prices all resolve to named entries under components/schemas.

Endpoints whose payload is genuinely dynamic — the settings singletons, guardrail configurations, SCIM envelopes and analytics result rows — are described as open JSON objects for now. The call, its path parameters and its error response are still fully described; only the body’s inner shape is left loose. Treat a generated model for those endpoints as a starting point rather than a contract.

Errors use one envelope. message is always there; code is added when the refusal has a stable name a client can branch on (name_taken, invalid_field, invalid_body, store_timeout, …), and field names the field an invalid_field refusal is about. A refusal with no stable code, such as a 401, 403 or 404, carries the message alone:

{ "error": { "message": "name must be 1-256 visible characters", "code": "invalid_field", "field": "name" } }

A write the current state does not allow answers 409 with a message that says what to change first. Deleting a provider that a route target or a provider group member still references is one: DELETE /api/v1/providers/{id} is refused, the provider is left in place, and the message names each route and group that uses it, as in provider 'openai' is used by route 'gpt-4o', provider group 'llama-fleet'; remove it from them before deleting it. Operations that can refuse this way list the 409 in the schema.

Stable error codes#

message is English text for the person reading it and may change between releases. code is part of the API and is never renamed, so branch on it — the dashboard uses it to show the refusal in the reader’s language. The status code of each refusal is listed below.

Credential-sealing requests without a configured ROLTER_KEK return 503 and error.code: "kek_unavailable", not a field-validation 400. Configure the existing deployment key on the control plane and restart it before retrying; do not generate a replacement key for a store that already contains sealed secrets. This applies to provider keys, MCP credentials, SSO client-secret writes, connector/channel credentials and second-factor enrolment. Existing sign-in and policy lockout refusals keep their own contracts.

{  "error": {    "message": "slug must match ^[a-z0-9][a-z0-9-]{0,62}$ (…)",    "code": "invalid_field",    "field": "slug"  }}

A few validation refusals still carry no code yet; treat a 400 or 409 without one by its status and message.

Analytics read errors#

The reads that query ClickHouse — /api/v1/analytics/*, /api/v1/health/*, /api/v1/mcp/logs* and /api/v1/me/usage — answer two distinct errors when the query does not come back, so a client can tell a slow query from a broken database:

An unconfigured ClickHouse is still a 503.