Reference

API reference

Endpoints, request/response shapes, headers

RealityRouter exposes an OpenAI-compatible API for the endpoints and features documented below.

API Compatibility Matrix

The following table summarizes the tested and verified compatibility of RealityRouter endpoints and advanced features:

Capability	Status	Notes
`POST /v1/chat/completions`	Supported	Full standard request/response body support.
`POST /v1/completions`	Supported	Legacy text completions.
`GET /v1/models`	Supported	Returns the list of currently active and discovered models.
Streaming / SSE	Supported	Verified streaming responses across all first-class adapters.
`tools` (Function Calling)	Supported	Translates client tools natively or converts to plain-text prompts if unsupported.
`tool_choice`	Supported	Standard selection rules are passed through or emulated.
JSON / Structured Output	Supported	Native schemas and strict JSON modes are enforced.
Image/Vision Input	Supported	Vision data is routed to vision-capable endpoints.
Audio Input	Not Supported	Planned in upcoming version.
OpenAI Responses API	Not Supported	Point custom clients to standard chat/completion endpoints instead.
Reasoning/Thinking fields	Supported	Pass-through for Anthropic and Google reasoning models.
Logprobs	Not Supported	Upstream logprobs are not currently aggregated.
Embeddings	Not Supported	Embedding endpoints are not intercepted or routed.

Base URL

With the router running locally, point your client at:

http://localhost:8000/v1

API key. Your client must send an Authorization header, but the value isn't validated. The router authenticates to upstream providers using keys in ~/.reality_router/.env.

POST /v1/chat/completions

Chat-based interactions. Same request shape as OpenAI:

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer anything" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "Refactor this function..."}
    ],
    "tools": [...],
    "temperature": 0.2
  }'

The `model` parameter

"auto" — let the router decide per-query. Recommended.
"gpt-5.4-thinking", "claude-opus-4", etc. — pin to a specific model. Useful for debugging or when you have hard constraints.
"tier:cheap", "tier:flagship" — bias the router toward a price tier without naming a specific model.

Supported / Tested Parameters

We support and actively test the following subset of request parameters:

messages (List of message objects; supports role user, assistant, system, and content as string or list of text blocks)
model (Pinning, tier-biasing, or auto-routing)
tools (Function-calling tool definitions)
temperature (Generation temperature)
max_tokens (Output token limit)
stream (Event stream control)

Response shape

Same as OpenAI's chat.completion response, with an additional x-rr-* set of headers exposing the routing decision:

X-RR-Model — which model handled the request.
X-RR-Strategy — single-shot or sequential.
X-RR-Attempts — how many models were tried before success.
X-RR-Cost — estimated USD cost of this request.
X-RR-Saved — estimated USD saved vs the always-flagship counterfactual.

POST /v1/completions

Legacy text completion. Same shape and headers as the OpenAI equivalent. Generally prefer /v1/chat/completions for new code.

GET /.well-known/agent-card.json

Standard agent-discovery endpoint for A2A communication. Returns the router's name, version, capabilities, and supported protocols.

curl http://localhost:8000/.well-known/agent-card.json

GET /health

Liveness check. Returns 200 OK with a small JSON body when the router is up:

{
  "status": "ok",
  "uptime_s": 3812,
  "models_active": 7,
  "models_quarantined": 1
}

GET /metrics/dashboard

The web dashboard UI. Renders the live view of spend, calibration, and per-agent activity. See the Dashboard guide.

Error codes

200 — success. Response body matches OpenAI's shape.
400 — malformed request (invalid JSON, missing required fields).
429 — concurrency limit exceeded on all eligible models. Retry after a moment.
502 Bad Gateway — infrastructure failure with the upstream provider (timeout, 500, invalid key). Inspect X-RR-Upstream-Error for details.
503 — all configured models are quarantined by the circuit breaker. Wait for recovery or check provider status.

Quality failures don't return errors. If a model returns broken JSON, truncated output, or an AI refusal, the router treats that as a quality failure and silently escalates to a better model. Your client only sees the validated response.