TL;DR — An agent router API is almost always an OpenAI-compatible chat-completions endpoint: you swap your tool's base URL for the router's, keep the same request format, and the router decides which underlying model serves each call. Integration is one config line in Cursor, Claude Code, Aider, or any SDK that accepts a custom base URL. The API features worth checking before committing:
model: "auto"support, per-request model attribution in responses, fallback behavior, and BYOK options. Examples for every major client below.
What "agent router API" actually means
There's no special protocol. A router exposes the same API shape your tools already speak — OpenAI's /v1/chat/completions (and increasingly Anthropic's /v1/messages) — and adds decision-making behind it:
- Your agent sends a normal completion request to the router's base URL
- The router classifies the request (phase, complexity, context size)
- It forwards to the chosen provider, handles retries/fallbacks
- The response comes back in the standard format, often with headers or metadata telling you which model actually served it
Because the contract is identical, adopting or leaving a router is a base-URL change — no SDK, no code rewrite. That's also your safety property: if the router disappears tomorrow, you point back at the provider and keep working (how to judge whether a router is trustworthy).
Calling a router API: examples
Raw HTTP (works with any OpenAI-compatible router):
curl https://api.coderouter.io/v1/chat/completions \
-H "Authorization: Bearer $CODEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{"role": "user", "content": "Write a binary search in Rust"}]
}'
The important detail is model: "auto" — that's what hands the model decision to the router. Pass a hardcoded model name and most routers will honor it, which silently bypasses routing (we learned this the expensive way).
Cursor: Settings → Models → override the OpenAI base URL with the router endpoint and paste your router key. Full walkthrough: Cursor base URL configuration guide.
Claude Code: set the environment variables for base URL and key — details and the 401 gotcha in the Claude Code custom base URL fix.
OpenAI SDK (Python):
from openai import OpenAI
client = OpenAI(
base_url="https://api.coderouter.io/v1",
api_key=os.environ["CODEROUTER_API_KEY"],
)
resp = client.chat.completions.create(model="auto", messages=[...])
API features that separate real routers from thin proxies
| Feature | Why it matters |
|---------|----------------|
| model: "auto" | Without it you're just proxying, not routing |
| Per-request attribution | Response tells you which model served the call — you can audit cost and quality |
| Automatic fallback | Provider outage → retry on alternative, not a 500 to your agent |
| BYOK support | Your own provider keys for custody or overage — opt-in on CodeRouter |
| Streaming parity | SSE streaming must pass through untouched or coding agents break |
| Reasoning-model handling | Thinking-mode fields must round-trip correctly (the reasoning_content trap) |
The one decision that matters: default model behavior
Most client tools ship configs that hardcode a frontier model name. If your router honors hardcoded names (most do), your traffic bypasses routing entirely and you save nothing. Two fixes: set model: "auto" in every client config, or use a router tier that routes regardless of the requested model. When we forced auto-routing on our own traffic, per-request cost dropped 36% overnight — the full data is here.