Quickstart

1. Get an API key

2. Pick the right base URL

Router One exposes two protocol surfaces. Which base URL you use depends on the client — this is the single most common setup mistake:

3. Send your first request

All endpoints authenticate with Authorization: Bearer <your key>. Pick your client:

curl https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

4. Stream responses

Set stream: true to receive an SSE stream — same shape as the official APIs, ending with data: [DONE]. The clients below reuse the setup from step 3.

curl -N https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short poem"}]
  }'

5. Choose a model

Use model: "auto" to let the gateway route within a server-owned candidate set (latency, posted cost, and reliability signals), or pin an exact model ID. IDs are case-sensitive — copy them from the model catalog.

6. Handle errors

Errors use standard HTTP status codes with a JSON body. The gateway retries and fails over within the same model family on 5xx/timeouts automatically; your client still needs to handle these:

Next steps