Quickstart

From zero to your first governed AI API call in under 5 minutes — a key, a provider, and your first request.

How it works

BrainstormRouter is a free, BYOK (Bring Your Own Key) AI gateway. You plug in your existing provider API keys (Anthropic, OpenAI, Google, and more) and BrainstormRouter routes traffic across them with capability-matched model selection, budget enforcement, and tamper-evident evidence for every request.

You pay your providers directly. BrainstormRouter never marks up token costs. The gateway itself is free — no credit card required.

1. Get an API key

One call creates a tenant and returns a live API key — no browser, no email verification. This is the path agents and headless apps use:

curl -X POST https://api.brainstormrouter.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{"tenant_name": "My Agent", "accept_tos": true}'

The response includes your key under api_key.key (starts with br_live_), your tenant id, and a dashboard claim URL:

{
  "tenant": { "id": "…", "name": "My Agent", "plan": "sandbox" },
  "api_key": { "key": "br_live_…", "scopes": ["admin"] },
  "claim": { "url": "https://brainstormrouter.com/dashboard/?claim=…" }
}

Copy the br_live_… key — you'll use it as your bearer token. New tenants start on the sandbox plan: 100 requests/day, 100K tokens/day, $2/day, cost-first routing. (Prefer a browser? Step 5 covers the dashboard.)

2. Add a provider key (BYOK)

Your very first completion works immediately — but with no provider key it returns a _simulated_ response (model brainstorm/sandbox), not a real model. Add one provider key so the "Hello, world!" below is real inference:

curl -X POST https://api.brainstormrouter.com/v1/providers \
  -H "Authorization: Bearer br_live_…" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-…"}'

Or, in the dashboard, go to Configure → Providers → Add Provider. Supported keys:

Provider	Where to get a key
Anthropic	console.anthropic.com
OpenAI	platform.openai.com
Google AI	aistudio.google.com
Groq	console.groq.com

Keys are encrypted at rest and never sent back to the browser. The more providers you add, the more models auto can route and fall back across.

3. Send your first request

Use any OpenAI-compatible SDK — just point the base URL at BrainstormRouter and set model: "auto":

curl https://api.brainstormrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.brainstormrouter.com/v1",
    api_key="br_live_…",
)

response = client.chat.completions.create(
    model="auto",  # BrainstormRouter picks the model
    messages=[{"role": "user", "content": "Hello, world!"}],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.brainstormrouter.com/v1",
  apiKey: "br_live_…",
});

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello, world!" }],
});

console.log(response.choices[0].message.content);

model: "auto" lets BrainstormRouter choose the model per request from complexity and your available providers. To pin one instead, pass any id from GET /v1/models — for example anthropic/claude-sonnet-5 or openai/gpt-5.5. (Model ids change as providers ship; GET /v1/models is always the source of truth.)

4. Inspect the decision

Every response carries X-BR-* headers describing what the router did. With curl, add -D - to print them:

X-BR-Routed-Model: deepseek/deepseek-v4-flash
X-BR-Selection-Method: capability-matched
X-BR-Route-Reason: capability-matched
X-BR-Actual-Cost: 0.000015
X-BR-Request-Id: req_01a044a0-cab3-7cb6-a946-c617143e1a45
X-BR-Explain: /v1/explain/req_01a044a0-cab3-7cb6-a946-c617143e1a45

X-BR-Explain links to the full decision trace (GET /v1/explain/{request_id}): the model selected, its score, and the priced alternatives it beat.

The OpenAI SDK doesn't expose response headers on the completion object — use the raw-response wrapper to read them:

raw = client.chat.completions.with_raw_response.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(raw.headers["X-BR-Routed-Model"])  # which model actually served
print(raw.headers["X-BR-Actual-Cost"])   # cost in USD
completion = raw.parse()
print(completion.choices[0].message.content)

5. Open the dashboard (optional)

The dashboard is the human fork — sign in at brainstormrouter.com/dashboard with GitHub or Google to claim the tenant you created above, watch live usage and evidence, set budgets and kill switches, and invite your team. Everything there is also available over the API.

What's happening under the hood

When you send a request, BrainstormRouter:

1. Authenticates your key and checks scope, rate limits, and budget.
2. Selects a model — auto is capability-matched: it floors to the tier the

task needs, then scores each eligible model on learned quality minus cost and tier-distance. See Auto Mode for the full algorithm.

1. Routes to the best available provider using your BYOK keys.
2. Falls back automatically if a provider fails (circuit breaker + cascade).
3. Records a tamper-evident evidence artifact and usage/cost metrics.

All of this happens in one request — no configuration required.

Next steps

• Graduation — Clear the sandbox caps with a verified provider key
• Authentication — Roles, RBAC, and key constraints
• Auto Mode — How capability-matched routing works
• Routing — Presets, variants, and model selection
• Budget & Kill Switch — Spend controls
• Headers Reference — All X-BR-* response headers