Router quickstart & integration guide

Runix Router is an OpenAI-compatible endpoint in front of many model providers. If your code already calls an OpenAI-compatible API, integration is a configuration change: point the client at Runix and swap the key. This guide covers the quickstart, model selection, streaming, failover semantics, and the operational details teams ask about. Router is in early access: keys are issued after a short intake, and onboarded teams get support directly from the engineers.

1. Quickstart

Set your client's base URL to https://api.router.runixcloud.io/v1 and use the key issued during onboarding. Everything else about your existing integration stays the same.

# cURL
curl https://api.router.runixcloud.io/v1/chat/completions \
  -H "Authorization: Bearer $RUNIX_API_KEY" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# OpenAI SDK (Python)
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.router.runixcloud.io/v1",
    api_key=os.environ["RUNIX_API_KEY"],
)
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
)

The same base-URL swap works for any tool that speaks the OpenAI API: LangChain, LlamaIndex, the Vercel AI SDK, or plain HTTP.

2. Model selection

Two ways to choose what serves a request:

• Pin a model id — pass a specific model id in the model field and Router dispatches to that model, applying failover only within the providers that serve it.
• Route automatically: pass "model": "auto" and Router selects by cost, health and your account's configuration. Routing preferences are set per key during onboarding; tell us your priorities (cheapest acceptable, latency-first, provider allowlists) and they are applied server-side.
• Discover what a key can call, GET /v1/models with your key returns the model ids that key is allowed to use, so you can list them from code instead of asking us.

Model ids are the vendors’ own. Anthropic models answer to their official hyphenated ids (claude-opus-5, claude-sonnet-4-6), and other vendors’ models keep their catalogue names: there is no Runix-specific alias table to maintain, so an id copied from a vendor’s announcement works as-is. The authoritative list for your key is always GET /v1/models.

3. Streaming

Pass "stream": true and responses arrive as standard server-sent events, exactly as your SDK already expects. Streaming passes through the router rather than being buffered and replayed, including tool-call deltas, so the first token is forwarded as soon as the provider emits it rather than after the response completes. That is a statement about the mechanism, not a performance claim: measure time to first token against the provider directly and you will see what the router costs you.

4. Failover semantics

What happens when an upstream provider degrades is the part worth reading twice:

• Errors, rate limits and timeouts trip a circuit breaker; the request is re-issued to a healthy alternative under a retry budget, so one provider's bad hour does not become your outage.
• Mid-stream failures are re-issued as well: see how streaming failover works for the mechanics and the edge cases.
• A degrading provider is taken out of rotation before it drags your latency, and returns when health checks pass.

For the background on failure taxonomy, read Model failover for production LLM traffic; why retries should be a spend budget rather than a count (and which errors deserve one at all) is covered in Retry budgets for LLM APIs.

5. Limits, usage and cost

• List-price metering (requests are metered per token at the upstream vendors’ published rates, with input, output, cached-read and cache-write tokens priced separately) the same structure the vendors themselves publish. We audit the rate table against the vendors’ own pricing pages; the mechanics of why token bills diverge from price lists, and how to check one by hand, are in Why your LLM bill doesn’t match the price list.
• Usage on every response: the usage object carries the full token breakdown, cached tokens included, so any single request can be reconciled against the rate card without asking us. Billing is usage-based in USD with itemised statements; see Pricing for how quotes work.
• Per-key quotas: each key carries limits and quotas set during onboarding, revocable and adjustable without a redeploy.
• Attribution: issue separate keys per team or product to get cost attribution along the lines your finance team actually asks about; the reasoning is covered in LLM cost attribution.

6. Errors and request ids

Errors come back as JSON in the shape your OpenAI-compatible client already parses: an error object carrying message, type and code.

// missing or invalid key -> HTTP 401
{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 20260805082847...)",
    "type": "runix_error"
  }
}

// a path under /v1 that does not exist -> HTTP 404
{
  "error": {
    "message": "Invalid URL (POST /v1/nope)",
    "type": "invalid_request_error",
    "param": "",
    "code": ""
  }
}

Two things worth knowing before you write error handling. First, branch on the HTTP status rather than on error.type: the status is what the OpenAI SDKs already map to their own exception classes, and it is the part that will not surprise you. Second, the request id lives inside message, not in a field of its own; quote it when you contact us and we can trace that exact call.

Paths outside /v1 on this host are not part of the API surface and do not return this envelope. Per-key quota and rate limits are set during onboarding (see section 5); when a limit or an upstream failure is involved, the router applies the failover behaviour in section 4 before an error reaches you.

7. Data handling

Prompt and response content is processed to serve your request; it is not used to train models and not sold. Operational metadata (usage counts, latency, error codes) is kept to run billing, reliability and support. The full statement is in the Privacy Policy, and the security posture in Security.

If you are evaluating us — or any gateway — the security review an LLM gateway should survive is the list of questions we think you should ask, including of Runix.

8. Getting a key

Router is currently invite-only: tell us what you are building — models, expected volume, latency needs — or email [email protected], and we reply within one business day and set the account up for you. Evaluation credits are issued on request, so you can test against real traffic before you pay. Existing accounts sign in here.