API reference
Endpoint
Base URL, authentication, the endpoints Router serves, and common errors.
Router serves every API request from a single base URL:
https://api.router.com/v1Point your SDK or HTTP client at this URL and authenticate with your Router API key. Make sure to keep /v1 in the base URL, since every endpoint lives under it.
Router supports the following endpoints. Each one accepts the same Router API key:
Endpoint | What it does | Reference |
|---|---|---|
GET /v1/models | Lists the models available to your key, with their limits, capabilities, and pricing | |
POST /v1/responses | Creates a model response using the OpenAI Responses API | |
POST /v1/messages | Creates a model response using the Anthropic Messages API | |
POST /v1/messages/count_tokens | Counts the input tokens of an Anthropic Messages request | |
POST /v1/decisions | Answers typed questions using the OpenAI Decisions API (limited availability) | |
POST /v1/systemone | Answers typed questions using the TypeSafe System One API | |
Router doesn't serve OpenAI Chat Completions, embeddings, files, or batches. If your application uses Chat Completions today, convert those calls to the Responses API. See Connect your app for a guided migration.
Send your Router API key in either the Authorization or the X-Api-Key HTTP header:
Authorization: Bearer <router-api-key>X-Api-Key: <router-api-key>If you send both headers, Router will use Authorization. Use your Router key here, not a provider key: Router holds the provider credentials, or uses your own provider keys if you've added them.
For example, to check that your key works:
curl "https://api.router.com/v1/models" \
-H "Authorization: Bearer $RAMP_ROUTER_API_KEY"When Router rejects a key, it returns 401 with one of two codes:
Code | When |
|---|---|
invalid_api_key | The key is missing, unknown, expired, or locked by a recurring spend cap |
api_key_deactivated | The key was disabled, including by a lifetime spend cap. The error message explains the reason |
Note that a deactivated key can be re-enabled, but an unknown key cannot. If your client shows this difference to its users, handle the two codes separately.
Beyond authentication, these are the errors you're most likely to see while getting started:
Status | What it usually means | What to do |
|---|---|---|
400 | The request body is malformed, or a field has an invalid value | Fix the field named by param, when present |
402 | Your account has no available credit | Add credit to your account |
404 | The model isn't available to your key | Use an ID from GET /v1/models |
429 | A provider or Router rate limit was reached | Respect the retry-after header, or add a fallback |
501 | The selected model or provider can't handle a feature your request uses | Remove the feature, or choose a model that supports it |
See Errors and limits for every status code and what to do about it.
Each endpoint returns errors in the format its API family uses, so the error handling built into your SDK keeps working:
-
GET /v1/models, POST /v1/responses, and POST /v1/decisions use the OpenAI error envelope:
{ "error": { "message": "Invalid API key.", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } -
POST /v1/messages and POST /v1/messages/count_tokens use the Anthropic error envelope:
{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid API key." } } -
POST /v1/systemone uses the TypeSafe error shape, {"detail": ...}.
Router echoes the x-request-id and x-trace-id headers, and generates either one if you don't send it. We recommend logging these values alongside your own application logs so you can find a request later. See Monitor and debug.
Successful responses from the inference endpoints also include an X-Router-Provider header naming the provider that served the request, such as openai or fireworks. This is useful when Router falls back to another provider or model, since the provider that answered may not be the first one Router tried.
