Skip to main content
Version: next

HTTP Endpoints

The service exposes five groups of HTTP endpoints on the same port (default: 3000):

GroupPath prefixAuthPurpose
LLM Proxy/v1/*Bearer router token (sk-rt-…)Forward requests to LLM providers
Pass-Through Proxyany other pathBearer router token (sk-rt-…)Transparently forward any unhandled provider endpoint
Management API/api/*Bearer JWT (dashboard session)Configure models, routers, users
MCP Server/mcpBearer personal MCP token (sk-rt-mcp-…)Model Context Protocol tools for MCP clients
Dashboard/dashboard/*Browser session (cookie)Serve the React web UI
Health/healthNoneLiveness probe

For the full request/response schemas of each route, see API — LLM Proxy and API — Management.


LLM Proxy​

These routes accept the same request bodies as the original provider APIs. Authentication is via a router token (Authorization: Bearer sk-rt-…).

Every request goes through the full routing and budget stack before being forwarded to a provider.

POST /v1/chat/completions​

OpenAI Chat Completions format. Supports both streaming ("stream": true) and non-streaming responses.

POST /v1/chat/completions
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN
Content-Type: application/json

{
"model": "gpt-5-mini",
"messages": [{ "role": "user", "content": "Hello!" }],
"stream": false
}

The model field is the model ID registered in your router. Routerly ignores it as an upstream model directive — the routing engine picks the actual provider model based on your policies.

POST /v1/responses​

OpenAI Responses API format (newer API surface). Uses input instead of messages, and streams only when "stream": true. Routerly normalises it to the chat/completions shape internally before routing, then answers in the Responses wire format — a response object, or the typed event:-named SSE sequence that ends on response.completed with no [DONE] sentinel.

previous_response_id is rejected with HTTP 400: Routerly keeps no conversation state, so the full input list must be sent each turn. See the LLM Proxy API for the supported item types and event sequence.

POST /v1/responses
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN
Content-Type: application/json

{
"model": "gpt-5-mini",
"input": [{ "role": "user", "content": "Hello!" }]
}

POST /v1/messages​

Anthropic Messages API format. The request body matches the Anthropic SDK wire format exactly.

POST /v1/messages
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN
Content-Type: application/json

{
"model": "claude-haiku-4-5",
"max_tokens": 1024,
"messages": [{ "role": "user", "content": "Hello!" }]
}

Routerly proxies this to the Anthropic provider adapter. If the selected model is an OpenAI model, the adapter translates the request format automatically.

GET /v1/models​

Returns the list of models available in the router associated with the token, in the OpenAI GET /v1/models response format.

GET /v1/models
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN

Error format​

All LLM Proxy errors follow the OpenAI error envelope:

{
"error": {
"message": "Budget exceeded for model gpt-5-mini",
"type": "budget_exceeded",
"code": "budget_exceeded"
}
}

Common status codes:

CodeCause
401Missing or invalid router token
503No model passed all routing filters (all excluded or over budget)
503Budget exhausted for the router or token
504Provider timeout

Pass-Through Proxy​

Any path that Routerly does not explicitly handle is transparently forwarded to the router's upstream provider. Only the API key is swapped — method, headers, body, and query string are passed through verbatim. This makes Routerly a true drop-in replacement for the full provider API surface, not just chat completions.

Authentication: same Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN header required for the LLM Proxy.

What it enables​

ProviderEndpoints now available via Routerly
OpenAI/v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech, /v1/files, /v1/fine-tuning/*, and any future endpoints
Anthropic/v1/complete, /v1/messages/batches, /v1/models, and any future endpoints
Ollama/api/embeddings, /api/tags, /api/pull, and more
Custom providersAny path your upstream accepts

Model selection​

When the request body contains a model field, Routerly matches it against the router's configured models (by ID or upstream model ID) and uses the corresponding provider credentials. If no match is found, or the request has no body, it falls back to the first configured model in the router.

Reserved namespaces​

The following paths are never proxied and always return a Routerly-native response:

PathBehaviour
/Redirect to /dashboard/
/healthHealth check response
/api/*Management API
/dashboard*Dashboard static files

Any request to these paths with a router token receives a standard 404, not a proxy attempt.

Example: embeddings​

POST /v1/embeddings
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN
Content-Type: application/json

{
"model": "text-embedding-3-small",
"input": "The quick brown fox"
}

Routerly finds the configured model matching text-embedding-3-small, injects the upstream API key, and forwards the request to https://api.openai.com/v1/embeddings. The response is streamed back as-is.

Error codes​

CodeCause
401Missing or invalid router token
502 no_upstreamRouter has no configured models
502 upstream_errorNetwork error reaching the upstream provider

Management API​

The Management API is used by the dashboard and the CLI. Authentication is via a JWT obtained from POST /api/auth/login.

Full endpoint catalogue: API — Management.

Key routes​

MethodPathDescription
POST/api/auth/loginObtain a JWT
GET/api/modelsList registered models
POST/api/modelsRegister a new model
PUT/api/models/:idUpdate a model
DELETE/api/models/:idRemove a model
GET/api/routersList routers
POST/api/routersCreate a router
GET/api/usageQuery usage records
GET/api/usage/:idRead one usage record by record id or trace id
GET/api/settingsRead service settings
PUT/api/settingsUpdate service settings
GET/api/usersList users (admin only)
GET/api/spend-groupsList org/team spend groups with usage
POST/api/spend-groupsCreate a spend group
PUT/api/spend-groups/:idUpdate a spend group
DELETE/api/spend-groups/:idDelete a spend group
GET/api/notifications/inboxList the current user's in-app notifications
POST/api/notifications/inbox/readMark notifications as read (ids[] or all)
GET/api/me/mcp-toolsList the MCP tools the caller's own tokens expose
GET/api/me/mcp-tokensList the caller's personal MCP tokens
POST/api/me/mcp-tokensCreate a personal MCP token (raw value returned once)
DELETE/api/me/mcp-tokens/:idRevoke a personal MCP token

MCP Server​

Routerly's mcp module exposes the gateway's own management API as tools to Model Context Protocol clients (Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and similar). This is a distinct surface from the LLM Proxy: /mcp never forwards anything to an upstream provider, it only reads and writes Routerly's own configuration and usage data through a fixed set of built-in tools. See Concepts: MCP Server for the full tool list and both transports.

POST /mcp​

Streamable HTTP transport, JSON-RPC 2.0. Self-authenticating: this route is excluded from the standard router-token auth guard and validates the token itself.

Authentication: Authorization: Bearer sk-rt-mcp-YOUR_MCP_TOKEN, a personal MCP token. Router tokens (sk-rt-…) are rejected: the token identifies a user, and the call runs with that user's permissions.

POST /mcp
Authorization: Bearer sk-rt-mcp-YOUR_MCP_TOKEN
Content-Type: application/json
Accept: application/json, text/event-stream

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{ "name": "list_models", "description": "...", "inputSchema": { "type": "object", "properties": {} } }
]
}
}

tools/list returns only the tools the token owner's role permits, and tools/call re-checks the same permission, so an under-permissioned client can neither see nor reach a tool it cannot use.

stdio transport​

For local MCP clients that spawn a subprocess (Claude Desktop and similar), run:

routerly mcp serve

This is a thin wrapper: it resolves an MCP token, then spawns the Routerly service binary with ROUTERLY_MCP_STDIO=1 and ROUTERLY_MCP_TOKEN=<token> set, which starts only the stdio MCP server bound to that token owner's identity. The identity is resolved once at startup, so a role change reaches a running session only after a restart. See Reference: Environment Variables if you are connecting a real MCP client directly to the service binary instead of via the CLI.

Error codes​

CodeCause
401Missing Authorization header
401Unknown or revoked token, or a router token used in place of an MCP token
401Token past its expiresAt

A tools/call the caller lacks the permission for does not fail at the HTTP level (still 200); the JSON-RPC result carries isError: true with an explanatory message.


Dashboard​

When dashboardEnabled: true (default), the service bundles and serves the React web UI as static files.

PathBehaviour
GET /dashboard/Serves index.html (React app entry point)
GET /dashboard/*Static assets (JS, CSS, icons) — falls back to index.html for client-side routes
GET /dashboardRedirects to /dashboard/
GET /Redirects to /dashboard/

To disable the dashboard (e.g. in a headless production deployment):

// settings.json
{ "dashboardEnabled": false }

Health Check​

GET /health

No authentication required. Returns HTTP 200 with a JSON body:

{
"status": "ok",
"version": "0.1.5",
"timestamp": "2026-03-27T12:00:00.000Z"
}

Suitable for Docker HEALTHCHECK, Kubernetes liveness probes, and load balancer checks.


Traces​

LLM Proxy responses carry no Routerly headers. To follow a request, send your own correlation id on it and read the entries on the management API while they happen:

POST /v1/chat/completions
x-routerly-trace: my-request-42
GET /api/traces/stream?correlationId=my-request-42

The id is consumed by Routerly: it is not forwarded upstream and changes neither the request nor the response payload. Once the request is done, its trace is on the usage record, and the dashboard shows it in Usage and in the Playground.