The Neural Router API

All requests are made over HTTPS to:

https://api.neuralrouter.ai/v1

Requests and responses follow the OpenAI Chat Completions schema exactly, the body is unmodified, so existing OpenAI client libraries work by setting only the base URL and API key.

Routing is controlled two ways, neither of which changes the request body: the model field accepts a routing alias, and optional X-NR-* request headers override behaviour per call. Every response carries X-NR-* headers describing the decision. See Routing headers.

Pass your workspace key as a bearer token. Keys are prefixed sk-nr- and scoped to one workspace.

Authorization: Bearer sk-nr-xxxxxxxxxxxxxxxxxxxx

Generate a model response for a conversation. Request parameters:

Example request body:

{
  "model": "auto",
  "messages": [
    { "role": "system", "content": "You are concise." },
    { "role": "user", "content": "Summarize routing in one line." }
  ],
  "temperature": 0.7,
  "max_tokens": 256,
  "stream": false
}

Example response:

{
  "id": "nrc_8f2a1c...",
  "object": "chat.completion",
  "created": 1782000000,
  "model": "claude-sonnet",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Routing sends each request to the best model for your objective." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 16, "total_tokens": 40 }
}

Routing is controlled with optional request headers, so the request body stays byte-for-byte OpenAI-compatible and any OpenAI SDK can send them without a schema override.

Alternatively, set the model field to a routing alias instead of a concrete id: auto defers to your workspace policy, cheapest selects on lowest cost, fastest on lowest time-to-first-token, and best on highest quality. Any other non-empty value is treated as a concrete model and pins the route.

curl https://api.neuralrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEURALROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-NR-Objective: lowest-latency" \
  -H "X-NR-Allow: gpt-4o,claude-sonnet" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

Every response carries the routing decision:

X-NR-Model: claude-sonnet
X-NR-Route-Reason: lowest-latency within allow-list
X-NR-Overhead-Ms: 7
X-NR-Trace-Id: nrq_8f2a1c4b
X-NR-Cache: miss

Returns the models available to your workspace, each with provider, pricing, context window, and live health.

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet",
      "provider": "Anthropic",
      "context_window": 200000,
      "input_per_m": 3.0,
      "output_per_m": 15.0,
      "health": "healthy"
    }
  ]
}

Create an embedding vector for the given input, OpenAI-compatible. Routing applies the same way, set model to a specific embedding model or "auto".

{
  "model": "auto",
  "input": "The quick brown fox."
}

When stream is true, the response is a sequence of server-sent events. Each event is a data: line carrying a chat.completion.chunk, ending with data: [DONE].

data: {"choices":[{"delta":{"content":"Rou"}}]}

data: {"choices":[{"delta":{"content":"ting"}}]}

data: [DONE]

Rate limits are per workspace and returned on every response via x-ratelimit-remaining and x-ratelimit-reset headers. A 429 indicates you should retry after the reset window with exponential backoff. Upstream provider 429s are absorbed by failover and do not count against your limit.

Errors use standard HTTP status codes and a JSON body of the form { "error": { "type", "message" } }.

New to the API? Start with the Documentation.