---
name: BrainstormRouter
bootstrap: POST https://api.brainstormrouter.com/v1/signup
self: GET https://api.brainstormrouter.com/v1/self
mcp: POST https://api.brainstormrouter.com/v1/mcp/connect
openapi: https://api.brainstormrouter.com/openapi.json
---

# BrainstormRouter

> AI Workforce Control Plane — runtime governance for non-human workers. Intelligent routing across 321 model endpoints (Claude, GPT, Gemini, Bedrock, Ollama) with graduated trust, agent identity, memory, Thompson sampling, guardrails, and governance.

## Agent Quick Start (3 steps)

### Phase 1: Get an API Key

#### Path A: Self-Service Signup (no invite code needed)

**Step 1 — Check terms of service (optional):**
```
GET https://api.brainstormrouter.com/v1/tos
→ { "version": "1.0", "summary": "...", "url": "https://brainstormrouter.com/legal/terms" }
```

**Step 2 — Initiate signup:**
```
POST https://api.brainstormrouter.com/v1/signup
{"email": "you@example.com", "tenant_name": "My AI Lab"}
→ { "message": "Verification code sent. Check your email.", "email": "you@example.com", "expires_in_seconds": 600 }
```

**Step 3 — Verify email with 6-digit code:**
```
POST https://api.brainstormrouter.com/v1/signup/verify
{"email": "you@example.com", "code": "123456"}
→ {
    "tenant": { "id": "uuid", "slug": "my-ai-lab", "name": "My AI Lab" },
    "api_key": { "id": "uuid", "key": "brk_...", "scopes": ["admin"] },
    "claim": { "url": "https://brainstormrouter.com/dashboard/?claim=...", "expires_at": "..." },
    "next_steps": { "register_provider": { "endpoint": "POST /v1/providers" } }
  }
```
Save the `api_key.key` — it is shown once. Open `claim.url` to link your dashboard account.

#### Path B: Invite Code (alternative)
```
POST https://api.brainstormrouter.com/v1/register
{"invite_code": "YOUR_CODE", "tenant_name": "My Agent", "admin_email": "me@example.com", "accept_tos": true}
→ Returns: { api_key: { key: "brk_..." }, tenant: {...}, claim: { url: "..." } }
```

#### Path C: CLI (guided wizard)
```
npm install -g @brainstormrouter/cli
br init
```
The `br init` wizard handles signup or login, adds a provider key, and sends your first completion.

### Phase 2: Add Provider Keys (BYOK)
```
POST /v1/providers  (Authorization: Bearer brk_...)
{"provider": "anthropic", "api_key": "sk-ant-..."}
```

### Phase 3: Make Completions
```
POST /v1/chat/completions
{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}
→ Set model="auto" for intelligent cost/quality routing
```

## Key Endpoints for Agents
- `GET /v1/self` — Full self-awareness: identity, health, budget, config, suggestions
- `GET /v1/discovery` — Capability discovery: routing strategies, health, budget, model stats
- `GET /v1/catalog/runnable` — Models that will actually work right now
- `GET /v1/health/providers` — Per-provider health with circuit breaker states
- `POST /v1/chat/completions` — Route completions (streaming + non-streaming)
- `POST /v1/messages` — Anthropic Messages API (same pipeline, Anthropic format)
- `GET /v1/models` — All discovered models
- `POST /v1/agent/bootstrap` — Create agent identity with budget + JWT
- `POST /v1/mcp/connect` — MCP server (Streamable HTTP)

## Intelligent Auto-Routing (model="auto")
Set `model: "auto"` to activate BrainstormRouter's intelligence engine:
1. **Thompson Sampling** (≥50 samples): Learns which models produce best results for your request shape. Uses UCB1 exploration below 500 samples, Gaussian Thompson Sampling above.
2. **Complexity-Based** (<50 samples): Scores request complexity (0–10) from message count, tools, images, tokens, content analysis, and memory signals. Routes: simple (<2) → cheapest, moderate (2–4) → mid-range, complex (≥5) → most capable.
3. **Cheapest Fallback**: When no history or complexity signal exists, picks the lowest-cost chat-capable model.

### Auto Variants
- `auto` — Best overall (quality-weighted Thompson sampling)
- `auto:fast` — Fastest model (latency-optimized)
- `auto:floor` — Cheapest model (cost-optimized)
- `auto:best` — Most capable model (quality-only, ignores cost)

Response headers expose the decision: `X-BR-Selection-Method`, `X-BR-Complexity-Level`, `X-BR-Complexity-Score`, `X-BR-Selection-Confidence`, `X-BR-Models-Considered`, `X-BR-Routed-Model`, `X-BR-Route-Reason`, `X-BR-Budget-Remaining`, `X-BR-Memory-Facts-Injected`, `X-BR-Cache`, `X-BR-Total-Latency-Ms`, `X-BR-Provider-Latency-Ms`, `X-BR-Routing-Overhead-Ms`.

Every error response includes a `recovery` field with machine-actionable next steps.

## CLI (`@brainstormrouter/cli`)
```
npm install -g @brainstormrouter/cli
```

### Getting Started
```
br init                        # Guided onboarding (signup or login, add provider, first completion)
br auth signup <email>         # Create account via email verification
br auth login-email <email>    # Log in with existing account
br auth login <key>            # Direct API key login
br auth status                 # Show current auth, tenant, key
```

### Daily Use
```
br chat "prompt"               # Send completion (model=auto by default)
br models                      # List available models
br providers add <name>        # Add provider API key interactively
br health                      # Provider health + circuit breaker states
br webhooks list               # List configured webhooks
br account                     # Tenant profile + user count
```

## Account & Tenant Management

All endpoints require `Authorization: Bearer brk_...` (API key with `config.read` or `config.write` scope).

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/account` | Tenant profile (name, plan, status, user count) |
| `PATCH` | `/v1/account` | Update tenant name |
| `GET` | `/v1/account/users` | List users in tenant |
| `POST` | `/v1/account/users/invite` | Invite user by email (generates claim URL) |
| `DELETE` | `/v1/account/users/:id` | Remove user from tenant |

### Example: Get tenant profile
```
GET /v1/account
→ { "tenant": { "id": "uuid", "slug": "my-lab", "name": "My AI Lab", "plan": "free", "user_count": 3 } }
```

### Example: Invite a user
```
POST /v1/account/users/invite
{"email": "teammate@example.com", "role": "member"}
→ { "invitation": { "email": "...", "role": "member", "claim_url": "https://brainstormrouter.com/dashboard/?claim=..." } }
```

## Webhooks

Event-driven notifications for completions, provider health, budget, keys, and anomalies.
All endpoints require `Authorization: Bearer brk_...`.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/webhooks` | Create webhook |
| `GET` | `/v1/webhooks` | List webhooks |
| `PATCH` | `/v1/webhooks/:id` | Update webhook (url, events, is_active) |
| `DELETE` | `/v1/webhooks/:id` | Delete webhook |
| `POST` | `/v1/webhooks/:id/test` | Send test event |
| `GET` | `/v1/webhooks/:id/deliveries` | Delivery history |

### Valid event types
`completion.created`, `completion.error`, `provider.down`, `provider.recovered`, `budget.threshold`, `budget.exceeded`, `key.created`, `key.revoked`, `anomaly.detected`

### Example: Create a webhook
```
POST /v1/webhooks
{"url": "https://example.com/hook", "events": ["completion.error", "provider.down"]}
→ {
    "webhook": {
      "id": "uuid", "url": "...", "events": [...], "is_active": true,
      "secret": "hex...",
      "note": "Save this secret — it won't be shown again. Use it to verify webhook signatures."
    }
  }
```
Deliveries include an `X-BR-Signature` header = HMAC-SHA256 of the JSON payload using your webhook secret.

## Terms of Service
```
GET /v1/tos  (no auth required)
→ { "version": "1.0", "summary": "...", "url": "https://brainstormrouter.com/legal/terms" }
```
Call before signup to display terms to the user.

## SDKs
- [TypeScript SDK](https://www.npmjs.com/package/brainstormrouter) — `npm install brainstormrouter`
- [Python SDK](https://pypi.org/project/brainstormrouter/) — `pip install brainstormrouter`
- [CLI](https://www.npmjs.com/package/@brainstormrouter/cli) — `npm install -g @brainstormrouter/cli`

## Agent Playbook (Full 12-Phase Guide)
- [Agent Playbook](https://brainstormrouter.com/llms-agent-playbook.txt) — step-by-step setup from zero to production

## API Reference
- [OpenAPI Spec](https://api.brainstormrouter.com/openapi.json)
- [Full API Reference (llms-full.txt)](https://brainstormrouter.com/llms-full.txt)
- [Completions](https://docs.brainstormrouter.com/api-reference/completions)
- [Models](https://docs.brainstormrouter.com/api-reference/models)
- [Memory](https://docs.brainstormrouter.com/api-reference/memory)
- [Security](https://docs.brainstormrouter.com/api-reference/security)
- [Guardrails](https://docs.brainstormrouter.com/api-reference/guardrails)
- [Observability](https://docs.brainstormrouter.com/api-reference/observability)
- [Governance](https://docs.brainstormrouter.com/api-reference/governance)

## Core Concepts
- [Intelligent Routing (Thompson Sampling)](https://docs.brainstormrouter.com/concepts/routing)
- [Agent Memory (4-Block RMM)](https://docs.brainstormrouter.com/concepts/memory)
- [Graduated Trust Degradation](https://docs.brainstormrouter.com/concepts/graduated-trust)
- [Guardrails](https://docs.brainstormrouter.com/concepts/guardrails)
- [Observability](https://docs.brainstormrouter.com/concepts/observability)

## Identity Bridge (Machine-to-Dashboard Linking)
- After registration, open the claim URL to link your dashboard account
- Generate additional claim links: `POST /v1/tenant/claim-link` (API key, admin scope)
- Device flow for terminal-to-browser linking: `POST /v1/auth/device/authorize` → display `user_code` → user enters at dashboard → poll `POST /v1/auth/device/token`

## MCP Control Plane
- BrainstormRouter operates as both MCP server (65 tools) and MCP gateway (register, govern, proxy external MCP servers)
- Secretless access: upstream credentials stored on server registrations, never exposed to agents
- Endpoint: `POST https://api.brainstormrouter.com/v1/mcp/connect`
- Transport: Streamable HTTP (per MCP spec)

### MCP Server Tools (65)
Routing & Models: br_route_completion, br_list_models, br_get_usage, br_set_alias, br_list_aliases, br_patch_aliases, br_get_health
Memory: br_memory_list, br_memory_store, br_memory_query, br_memory_delete, br_memory_update, br_memory_shared_store, br_memory_shared_list
Config: br_list_prompts, br_list_presets, br_list_config, br_get_config, br_set_config
Ops & Insights: br_get_ops_status, br_get_insights, br_get_governance, br_get_insights_daily, br_get_insights_forecast
Agents: br_list_agents, br_get_leaderboard, br_bootstrap_agent, br_agent_status, br_agent_limits, br_agent_anomaly
Delegation: br_delegate_agent, br_list_sub_agents, br_terminate_sub_agent
Capacity: br_get_capacity
Security: br_get_security_status, br_get_policies, br_test_policy, br_get_siem_config, br_update_siem_config
Guardrails: br_get_guardrail_config, br_update_guardrail_config, br_test_guardrails, br_guardrail_metrics
Budget: br_get_budget_status, br_get_budget_forecast
Kill Switch: br_activate_killswitch, br_deactivate_killswitch, br_get_killswitch_status, br_killswitch_scope, br_list_killswitch_scopes, br_deactivate_killswitch_scope
Governance: br_policy_dry_run, br_replay_decisions, br_session_timeline, br_forensic_snapshots
Approvals: br_list_pending_approvals, br_approve_request, br_reject_request
Platform Admin: br_list_tenants, br_approve_tenant, br_reject_tenant, br_get_business_digest, br_create_invite_code
MCP Gateway: br_mcp_server_health
RBAC: br_my_permissions

## Integration Guides
- [LangChain](https://docs.brainstormrouter.com/guides/langchain)
- [LlamaIndex](https://docs.brainstormrouter.com/guides/llamaindex)
- [CrewAI](https://docs.brainstormrouter.com/guides/crewai)
- [Vercel AI SDK](https://docs.brainstormrouter.com/guides/vercel-ai)