# BrainstormRouter — Agent Playbook

> This document tells an AI agent how to set up, configure, and operate
> BrainstormRouter from scratch. Read this BEFORE calling any endpoints.
> Base URL: https://api.brainstormrouter.com

## Phase 1: Get an API Key

You need a `brk_` API key. There are four paths:

### Path A: Self-Service Signup (recommended — no invite code needed)
```bash
# Step 1: Initiate signup
curl -X POST https://api.brainstormrouter.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "tenant_name": "My AI Lab"}'
# → { "message": "Verification code sent.", "expires_in_seconds": 600 }

# Step 2: Verify with 6-digit code from email
curl -X POST https://api.brainstormrouter.com/v1/signup/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'
# → { "api_key": { "key": "brk_..." }, "tenant": {...}, "claim": { "url": "..." } }
```
Save the `api_key.key` from the response. It is shown once.
Open the `claim.url` to link your dashboard account.

### Path B: Invite Code (alternative)
```bash
curl -X POST https://api.brainstormrouter.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "invite_code": "YOUR-CODE",
    "tenant_name": "My AI Lab",
    "admin_email": "you@example.com",
    "accept_tos": true
  }'
```

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

### Path D: Someone gave you an API key
Skip to Phase 2.

---

## Phase 2: Register Provider Keys (BYOK)

BrainstormRouter routes to AI providers but needs YOUR API keys for them.
Register at least one provider before making completions.

### Common providers (self-service with API key)

| Provider | ID | Key prefix | Env var |
|----------|-----|-----------|---------|
| Anthropic | `anthropic` | `sk-ant-*` | `ANTHROPIC_API_KEY` |
| OpenAI | `openai` | `sk-*` | `OPENAI_API_KEY` |
| Google Gemini | `google` | `AI*` | `GOOGLE_API_KEY` |
| Groq | `groq` | `gsk_*` | `GROQ_API_KEY` |
| Together AI | `together-ai` | varies | `TOGETHER_API_KEY` |

Full catalog: `GET /v1/providers/catalog` (no auth required).

### Step 1: Test key FIRST

Always validate before storing. The test endpoint returns HTTP 200 with
`{ valid: false }` for bad credentials (NOT an HTTP 401). Branch on the
`valid` field, not the HTTP status code.

```bash
curl -X POST https://api.brainstormrouter.com/v1/providers/test \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-..."}'
# → { "valid": true, "provider": "anthropic", "name": "Anthropic", "status": 405 }
# → { "valid": false, ..., "error": "Authentication failed — check your API key." }
```

### Step 2: Store key AFTER test passes

```bash
curl -X POST https://api.brainstormrouter.com/v1/providers \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-..."}'
# → 201 { "id": "uuid", "provider": "anthropic", "masked_key": "sk-ant-...wxyz", "status": "active" }
```

### Step 3 (alternative): Batch registration

Register multiple providers at once. Set `test_first: true` to validate
each key before storing.

```bash
curl -X POST https://api.brainstormrouter.com/v1/providers/batch \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [
      { "provider": "anthropic", "api_key": "sk-ant-...", "test_first": true },
      { "provider": "openai", "api_key": "sk-...", "test_first": true },
      { "provider": "google", "api_key": "AI...", "test_first": true }
    ]
  }'
# → 207 { "results": [...], "summary": { "total": 3, "stored": 2, "failed": 1 } }
```

### Error handling

- `POST /v1/providers`: `500` = storage/encryption misconfigured (check logs),
  `400` = missing field or unknown provider.
- `POST /v1/providers/test`: Returns HTTP 200 with `{ valid: false, status: 401|403 }`
  for bad credentials (NOT an HTTP 401). Branch on `valid` field, not HTTP status.
  Only returns HTTP 400 for malformed input/unknown provider.
- `POST /v1/providers/batch`: `400` = duplicate providers in batch or missing fields,
  `207` = per-provider results (check each item's `status` field: "stored" or "test_failed" or "store_failed").

---

## Phase 3: Make Completions

The completions endpoint is OpenAI-compatible. Model IDs use `provider/model` format.

### First: Discover what's available

```bash
# Discovery endpoint — call this first after authenticating
curl https://api.brainstormrouter.com/v1/discovery \
  -H "Authorization: Bearer br_live_YOUR_KEY"
# → routing strategies, provider health, budget, model counts, intelligence headers

# List available models
curl https://api.brainstormrouter.com/v1/models \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# List only models that will work right now (healthy + BYOK key present)
curl https://api.brainstormrouter.com/v1/catalog/runnable \
  -H "Authorization: Bearer br_live_YOUR_KEY"
```

### Explicit model selection

```bash
curl -X POST https://api.brainstormrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### Auto-routing (recommended)

Set `model: "auto"` to let BrainstormRouter pick the best model for your request:

```bash
curl -X POST https://api.brainstormrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

Auto-routing uses three strategies (in priority order):
1. **Thompson Sampling** (≥50 samples): Learns which models produce best results.
2. **Complexity-Based** (<50 samples): Scores request complexity (0–10). Routes: simple → cheapest, moderate → mid-range, complex → most capable.
3. **Cheapest Fallback**: No history → picks lowest-cost chat-capable model.

### Auto variants (constrained auto-routing)

| Model value   | Behavior |
|---------------|----------|
| `auto`        | Best overall model (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) |

### Intelligence headers

Every completion response includes `X-BR-*` headers exposing the routing decision:

| Header | Value |
|--------|-------|
| `X-BR-Selection-Method` | `thompson-sampling`, `complexity-based`, `cheapest-fallback`, `explicit` |
| `X-BR-Complexity-Level` | `simple`, `moderate`, `complex` |
| `X-BR-Complexity-Score` | Raw score 0–10 |
| `X-BR-Selection-Confidence` | 0.00–1.00 |
| `X-BR-Models-Considered` | Count of eligible models |
| `X-BR-Routed-Model` | `provider/model` actually used |
| `X-BR-Route-Reason` | Why this model was chosen |
| `X-BR-Budget-Remaining` | Remaining budget in USD |
| `X-BR-Memory-Facts-Injected` | Count of memory facts injected |
| `X-BR-Cache` | `hit` if semantic cache served the response |
| `X-BR-Total-Latency-Ms` | End-to-end request time |
| `X-BR-Provider-Latency-Ms` | Upstream provider time only |
| `X-BR-Routing-Overhead-Ms` | BrainstormRouter overhead |

### Semantic cache

If a semantically similar request was recently answered, BrainstormRouter may
serve the cached response (indicated by `X-BR-Cache: hit`). This saves cost
and latency with no configuration required.

### Error recovery

Every error response includes a `recovery` field with machine-actionable next steps:
```json
{
  "error": { "type": "budget_exceeded", "message": "..." },
  "recovery": {
    "action": "increase_budget",
    "endpoint": "PATCH /v1/agent-limits",
    "message": "Daily budget exhausted. Increase limit or wait for reset."
  }
}
```

At this point you have a working AI gateway. Phases 4+ add agent identity,
budgets, delegation, guardrails, and governance.

---

## Phase 4: Bootstrap Agent Identity

Agent profiles give each agent its own identity, budget, and audit trail.
Bootstrap creates a profile AND issues a JWT in one call.

```bash
curl -X POST https://api.brainstormrouter.com/v1/agent/bootstrap \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "researcher-01",
    "display_name": "Research Agent",
    "cost_center": "research",
    "budget_daily_usd": 5.00,
    "budget_monthly_usd": 100.00
  }'
```

Response includes:
- `profile` — the agent's profile (id, budget, lifecycle state)
- `jwt` — a 1-hour JWT for agent-authenticated requests
- `budget` — enforced limits
- `next_steps` — what to do next (cert exchange, status check)

The JWT can be used as a Bearer token instead of the API key. This lets
the agent act with its own identity and budget.

```bash
# Agent checks its own status
curl https://api.brainstormrouter.com/v1/agent/status \
  -H "Authorization: Bearer eyJ_AGENT_JWT..."

# Agent checks its budget/limits
curl https://api.brainstormrouter.com/v1/agent/limits/me \
  -H "Authorization: Bearer eyJ_AGENT_JWT..."

# Agent makes a completion (charged against its budget)
curl -X POST https://api.brainstormrouter.com/v1/chat/completions \
  -H "Authorization: Bearer eyJ_AGENT_JWT..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Summarize this paper..."}]
  }'
```

---

## Phase 5: Create Scoped API Keys (Virtual Keys)

Create restricted API keys for different teams, agents, or use cases.
Each key can have role scopes, model allowlists, rate limits, and budgets.

```bash
# Create a developer key limited to Claude models, 10 RPM, $5/day
curl -X POST https://api.brainstormrouter.com/v1/api-keys \
  -H "Authorization: Bearer br_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dev Team Key",
    "scopes": ["developer"],
    "allowed_models": ["anthropic/claude-sonnet-4", "anthropic/claude-haiku-4-5"],
    "rate_limit_rpm": 10,
    "budget_limit_usd": "5.00",
    "budget_period": "daily",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

# Create an agent-scoped key (minimal permissions)
curl -X POST https://api.brainstormrouter.com/v1/api-keys \
  -H "Authorization: Bearer br_live_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worker Agent Key",
    "scopes": ["agent"],
    "rate_limit_rpm": 30,
    "budget_limit_usd": "2.00",
    "budget_period": "daily"
  }'

# List all keys
curl https://api.brainstormrouter.com/v1/api-keys \
  -H "Authorization: Bearer br_live_YOUR_ADMIN_KEY"

# Revoke a key
curl -X DELETE https://api.brainstormrouter.com/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer br_live_YOUR_ADMIN_KEY"
```

Valid scopes (roles): admin, operator, developer, auditor, agent.
You cannot create a key with higher privileges than your own.

---

## Phase 6: Set Agent-Level Budgets & Rate Limits

Override per-agent limits beyond what the profile specifies.
These are enforced in real-time via Redis.

```bash
# Set limits for specific agents
curl -X PATCH https://api.brainstormrouter.com/v1/agent-limits \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent:researcher-01": {
      "maxBudgetUsd": 10.0,
      "maxRequestsPerMinute": 20
    },
    "agent:writer-01": {
      "maxBudgetUsd": 5.0,
      "maxRequestsPerMinute": 10
    }
  }'

# Read current limits
curl https://api.brainstormrouter.com/v1/agent-limits \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Remove an agent's limits (set to null)
curl -X PATCH https://api.brainstormrouter.com/v1/agent-limits \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent:researcher-01": null}'
```

---

## Phase 7: Configure Guardrails

Guardrails scan inputs and outputs for policy violations (PII, jailbreaks,
toxic content, secrets). Configure a pipeline of providers.

```bash
# See available guardrail providers (built-in + templates for external)
curl https://api.brainstormrouter.com/v1/guardrails/providers
curl https://api.brainstormrouter.com/v1/guardrails/templates

# Register an external guardrail provider (e.g., Lakera Guard)
curl -X POST https://api.brainstormrouter.com/v1/guardrails/providers \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "lakera",
    "name": "Lakera Guard",
    "template": "lakera",
    "api_key": "lak_..."
  }'

# Configure the guardrail pipeline
curl -X PUT https://api.brainstormrouter.com/v1/config/guardrails \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [
      {"id": "builtin-pii", "enabled": true},
      {"id": "lakera", "enabled": true}
    ],
    "chain_mode": "serial",
    "fail_open": false
  }'

# Test the pipeline with sample text
curl -X POST https://api.brainstormrouter.com/v1/guardrails/test \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "My SSN is 123-45-6789", "direction": "outbound"}'

# Read current config
curl https://api.brainstormrouter.com/v1/config/guardrails \
  -H "Authorization: Bearer br_live_YOUR_KEY"
```

---

## Phase 8: Delegate to Sub-Agents (Agent Swarms)

A parent agent can spawn child agents with sliced budgets.
The parent must have `can_delegate: true` in its metadata and a finite budget.

```bash
# Parent agent delegates to a child
curl -X POST https://api.brainstormrouter.com/v1/agent/delegate \
  -H "Authorization: Bearer eyJ_PARENT_JWT..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sub-researcher-01",
    "requested_role": "agent",
    "requested_name": "Sub-Researcher",
    "budget_allocation_usd": 2.00,
    "ttl_seconds": 3600,
    "metadata": {"task": "literature review"}
  }'

# Parent lists its children
curl https://api.brainstormrouter.com/v1/agent/sub-agents \
  -H "Authorization: Bearer eyJ_PARENT_JWT..."

# Parent terminates a child (budget reclaimed)
curl -X DELETE https://api.brainstormrouter.com/v1/agent/sub-agents/sub-researcher-01 \
  -H "Authorization: Bearer eyJ_PARENT_JWT..."
```

Constraints:
- Child role must be equal or lower privilege than parent
- Parent must retain at least $0.01 after delegation
- Child inherits parent's tenant
- Delegation is idempotent on agent_id

---

## Phase 9: Agent Lifecycle Management

Manage agent profiles through their lifecycle states:
provisioned → active → quarantined → suspended → terminated

```bash
# List all agent profiles
curl https://api.brainstormrouter.com/v1/agent/profiles \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Read a specific profile
curl https://api.brainstormrouter.com/v1/agent/profiles/researcher-01 \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Update an agent's budget or metadata
curl -X PATCH https://api.brainstormrouter.com/v1/agent/profiles/researcher-01 \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "budgetDailyUsd": 20.0,
    "metadata": {"can_delegate": true, "team": "research"}
  }'

# Transition lifecycle state (e.g., quarantine a misbehaving agent)
curl -X PATCH https://api.brainstormrouter.com/v1/agent/profiles/lifecycle/researcher-01 \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "quarantined"}'

# Archive (soft delete) an agent
curl -X DELETE https://api.brainstormrouter.com/v1/agent/profiles/researcher-01 \
  -H "Authorization: Bearer br_live_YOUR_KEY"
```

---

## Phase 10: Governance & Observability

Monitor agent behavior, audit memory operations, detect anomalies,
and review spending.

```bash
# Executive governance summary
curl https://api.brainstormrouter.com/v1/governance/summary \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Completion audit trail (who called what, when, how much)
curl "https://api.brainstormrouter.com/v1/governance/completion-audit?limit=50" \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Anomaly scores (real-time)
curl https://api.brainstormrouter.com/v1/governance/anomaly/scores \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Anomaly history for a specific agent
curl "https://api.brainstormrouter.com/v1/governance/anomaly/history?agent_id=researcher-01&limit=20" \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Memory audit (what memory ops happened)
curl "https://api.brainstormrouter.com/v1/governance/memory/audit?limit=100" \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Memory compliance scan (PII, secrets detection)
curl https://api.brainstormrouter.com/v1/governance/memory/compliance \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Cost insights
curl https://api.brainstormrouter.com/v1/insights/daily \
  -H "Authorization: Bearer br_live_YOUR_KEY"

curl https://api.brainstormrouter.com/v1/insights/waste \
  -H "Authorization: Bearer br_live_YOUR_KEY"

curl https://api.brainstormrouter.com/v1/insights/optimize \
  -H "Authorization: Bearer br_live_YOUR_KEY"

curl https://api.brainstormrouter.com/v1/insights/forecast \
  -H "Authorization: Bearer br_live_YOUR_KEY"

# Usage by cost center (maps to agent cost_center field)
curl "https://api.brainstormrouter.com/v1/usage/by-cost-center?period=month" \
  -H "Authorization: Bearer br_live_YOUR_KEY"
```

---

## Phase 11: Agent Memory

Store and query persistent memory across agent sessions.
Four memory blocks: **human**, **system**, **project**, **general**.

| Block | Purpose | Examples |
|-------|---------|----------|
| `human` | Facts about the user/human interacting with the agent | "User prefers concise responses", "User is a data scientist" |
| `system` | Governance rules, policies, agent instructions | "Always cite sources", "Max response length: 500 words" |
| `project` | Project-specific context and knowledge | "Project uses React 19", "Deadline is March 30" |
| `general` | Everything else — general knowledge, learned facts | "Company founded in 2020", "Product supports 3 languages" |

```bash
# Store a fact
curl -X POST https://api.brainstormrouter.com/v1/memory/entries \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fact": "User prefers concise responses", "block": "human", "pinned": true}'

# Query by semantic similarity
curl -X POST https://api.brainstormrouter.com/v1/memory/query \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query_text": "response style preferences", "block": "human", "limit": 5}'

# Bulk pre-load from documents
curl -X POST https://api.brainstormrouter.com/v1/memory/init \
  -H "Authorization: Bearer br_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "block": "general",
    "documents": [
      {"title": "Company Policy", "content": "All responses must be under 500 words..."},
      {"title": "Product FAQ", "content": "Our product supports..."}
    ]
  }'

# List memory blocks
curl https://api.brainstormrouter.com/v1/memory/blocks \
  -H "Authorization: Bearer br_live_YOUR_KEY"
```

---

## Phase 12: Cryptographic Identity (Optional, Advanced)

Exchange the agent JWT for a short-lived mTLS client certificate.
This enables mutual TLS authentication (strongest identity).

```bash
# Generate RSA key + CSR
openssl req -new -newkey rsa:2048 -nodes \
  -keyout agent.key -out agent.csr \
  -subj "/CN=researcher-01"

# Exchange JWT + CSR for signed certificate
curl -X POST https://api.brainstormrouter.com/v1/agent/auth/cert \
  -H "Authorization: Bearer eyJ_AGENT_JWT..." \
  -H "Content-Type: application/json" \
  -d "{\"csr_pem\": \"$(cat agent.csr)\"}"

# Response: { cert_pem, serial_number, expires_at (5 min), ca_cert_pem }

# Use mTLS for subsequent requests
curl --cert agent-cert.pem --key agent.key --cacert ca.pem \
  https://api.brainstormrouter.com/v1/agent/status
```

---

## Quick Reference: Key Discovery Endpoints

| Endpoint | Purpose |
|----------|---------|
| `GET /v1/discovery` | First call after auth — capabilities, health, budget, model stats |
| `GET /v1/self` | Full self-awareness: identity, health, budget, memory, config, suggestions |
| `GET /v1/catalog/runnable` | Models that will actually work right now |
| `GET /v1/health/providers` | Per-provider health with circuit breaker states |

---

## Decision Guide: What to Set Up

| You want to... | Do this |
|----------------|---------|
| Just route completions | Phases 1-3 only |
| Track per-agent spending | Add Phase 4 (bootstrap) |
| Limit what a key can do | Add Phase 5 (scoped keys) |
| Cap agent budgets | Add Phase 6 (agent limits) |
| Scan for PII/jailbreaks | Add Phase 7 (guardrails) |
| Build agent swarms | Add Phase 8 (delegation) |
| Audit everything | Add Phase 10 (governance) |
| Give agents persistent memory | Add Phase 11 (memory) |
| Strongest agent identity | Add Phase 12 (mTLS) |