API reference

Endpoint

Base URL, authentication, and the routes Router implements.

Router implements three OpenAI routes — model listing, response creation, and a Chat Completions compatibility surface — under one base URL:

https://api.router.com/v1

Authentication

Send a Router API key using either header:

Authorization: Bearer <router-api-key>

X-Api-Key: <router-api-key>

Authorization wins when both are present. Rejected keys return 401 with one of two codes:

Code	When
`invalid_api_key`	The key is unknown, expired, or locked by a recurring spend cap
`api_key_deactivated`	The key was disabled, including by a lifetime spend cap. The message carries the reason

A deactivated key can be re-enabled; an unknown one cannot. Handle them separately if your client surfaces the difference.

`GET /v1/models`

Returns the models available to the current key, in the OpenAI model-list shape. See Choose a model.

curl "https://api.router.com/v1/models" \
  -H "Authorization: Bearer $RAMP_ROUTER_API_KEY"

`POST /v1/responses`

Accepts an OpenAI Responses create payload plus a few Router-only fields. See Request fields for the full list.

curl "https://api.router.com/v1/responses" \
  -H "Authorization: Bearer $RAMP_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "input": "Reply with exactly one word: pong.",
    "max_output_tokens": 16
  }'

A buffered request returns one OpenAI Response object. stream: true returns OpenAI Responses server-sent events.

`POST /v1/chat/completions`

Accepts an OpenAI Chat Completions payload for clients that only speak the Chat Completions format. Requests are translated onto the same models and routing as /v1/responses.

curl "https://api.router.com/v1/chat/completions" \
  -H "Authorization: Bearer $RAMP_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Reply with exactly one word: pong."}],
    "max_completion_tokens": 16
  }'

A buffered request returns one chat.completion object. stream: true returns chat.completion.chunk server-sent events ending with data: [DONE]; send stream_options: {"include_usage": true} to receive usage in the final chunk. The surface covers streaming, function tool calls, usage, image input, and response_format. Controls Router cannot translate faithfully — logprobs, n greater than 1, legacy functions/function_call, audio, seed, logit_bias, non-zero penalties — return 501 not_implemented rather than being silently dropped. A few controls are model-dependent — stop sequences, response_format type json_object, and verbosity — and are translated natively where the serving provider supports them; where it does not, the request returns a 501 instead of silently dropping the control.

Request correlation

Router echoes x-request-id and x-trace-id, generating either one when you do not send it. See Monitor and debug.