# BrainstormRouter — Complete API Reference

> Autonomous AI API Engine — intelligent routing across 321 model endpoints
> (Claude, GPT, Gemini, Bedrock, Ollama) with built-in memory, Thompson sampling,
> guardrails, and governance.

Base URL: https://api.brainstormrouter.com
OpenAPI Spec: https://api.brainstormrouter.com/openapi.json
Docs: https://docs.brainstormrouter.com

---

## Authentication

### API Key (most common)
```
Authorization: Bearer brk_your_api_key_here
```
Create keys via dashboard or `POST /v1/api-keys`.

### Supabase JWT (dashboard users)
```
Authorization: Bearer eyJhbGciOiJSUzI1NiI...
```
Used by the SaaS dashboard at brainstormrouter.com/dashboard.

### Agent JWT (CAF agents)
```
Authorization: Bearer <agent-jwt>
```
For agents with cryptographic identity (CAF Phase 2).

### mTLS (mesh agents)
Agents with issued certificates authenticate via mutual TLS.

### SCIM Bearer Token
```
Authorization: Bearer <scim-token>
```
For identity provider integration (Okta, Azure AD, etc.).

---

## API Routes

### Health
Auth: None

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /health | Health check | server.ts |

### Discovery
Auth: None

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /llms.txt |  | server.ts |

### OpenAPI
Auth: None

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /openapi.json |  | server.ts |

### Signup & Onboarding
Auth: None

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/signup | Start signup: validate email, send 6-digit code | signup.ts |
| POST   | /v1/signup/verify | Verify code: create tenant + user + API key atomically | signup.ts |
| GET    | /v1/tos | Returns current TOS version, summary, and full URL. | tos.ts |

### Account Management
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/account | Tenant profile | account.ts |
| PATCH  | /v1/account | Update tenant name/settings | account.ts |
| GET    | /v1/account/users | List users in tenant | account.ts |
| DELETE | /v1/account/users/:id | Remove user from tenant | account.ts |
| POST   | /v1/account/users/invite | Invite user by email | account.ts |

### Webhooks
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/webhooks | Create webhook | webhooks.ts |
| GET    | /v1/webhooks | List webhooks | webhooks.ts |
| DELETE | /v1/webhooks/:id | Delete webhook | webhooks.ts |
| PATCH  | /v1/webhooks/:id | Update webhook | webhooks.ts |
| GET    | /v1/webhooks/:id/deliveries | Delivery history | webhooks.ts |
| POST   | /v1/webhooks/:id/test | Send test event | webhooks.ts |

### Completions & Embeddings
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/embeddings | OpenAI-compatible embeddings endpoint. | embeddings.ts |

### Models
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/models | Model listing. | models.ts |
| GET    | /v1/models/:provider/:modelId/capabilities | Per-model capability profile. | model-capabilities.ts |
| GET    | /v1/models/leaderboard | Model performance rankings. | leaderboard.ts |

### Memory
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/memory/approval-config |  | memory.ts |
| PUT    | /v1/memory/approval-config |  | memory.ts |
| GET    | /v1/memory/blocks | List all memory blocks with entry counts. | memory.ts |
| GET    | /v1/memory/blocks/:block | List entries in a specific block. | memory.ts |
| POST   | /v1/memory/blocks/sync | Bulk upsert core memory blocks. | memory.ts |
| GET    | /v1/memory/entries | List all core memory entries. | memory.ts |
| POST   | /v1/memory/entries | Append a new core memory entry. | memory.ts |
| PUT    | /v1/memory/entries/:id | Update an existing memory entry. | memory.ts |
| DELETE | /v1/memory/entries/:id | Delete a memory entry. | memory.ts |
| POST   | /v1/memory/init | Bootstrap memory from context documents. | memory.ts |
| GET    | /v1/memory/pending | list pending memory writes | memory.ts |
| POST   | /v1/memory/pending/:id/approve | approve a pending write | memory.ts |
| POST   | /v1/memory/pending/:id/reject | reject a pending write | memory.ts |
| POST   | /v1/memory/query |  | memory.ts |
| GET    | /v1/memory/shared/entries | list shared memory entries | memory.ts |
| POST   | /v1/memory/shared/store | store a shared (tenant-wide) memory entry | memory.ts |
| POST   | /v1/memory/store |  | memory.ts |

### Prompts
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/prompts | Create a prompt template | prompts.ts |
| GET    | /v1/prompts | List all prompts | prompts.ts |
| GET    | /v1/prompts/:id | Get prompt with version history | prompts.ts |
| PUT    | /v1/prompts/:id | Update (auto-creates new version) | prompts.ts |
| DELETE | /v1/prompts/:id | Archive a prompt | prompts.ts |
| POST   | /v1/prompts/:id/ab | Start/stop A/B test | prompts.ts |
| GET    | /v1/prompts/:id/ab | Get A/B test results | prompts.ts |
| GET    | /v1/prompts/:id/diff | Unified diff between two versions | prompts.ts |
| POST   | /v1/prompts/:id/evaluate | Run prompt against test cases with scoring | prompts.ts |
| GET    | /v1/prompts/:id/evaluate/results | List evaluation runs | prompts.ts |
| GET    | /v1/prompts/:id/evaluate/results/:runId/export | Export run as CSV/JSON | prompts.ts |
| POST   | /v1/prompts/:id/promote | Promote a version to higher environment | prompts.ts |
| POST   | /v1/prompts/:id/test | Test-resolve a prompt with variables | prompts.ts |

### Presets
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/presets | Create a preset | presets.ts |
| GET    | /v1/presets | List all presets | presets.ts |
| GET    | /v1/presets/:slug | Get a preset | presets.ts |
| PUT    | /v1/presets/:slug | Update a preset | presets.ts |
| DELETE | /v1/presets/:slug | Archive a preset | presets.ts |

### Tasks
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/tasks | Schedule a new background agent task. | tasks.ts |
| GET    | /v1/tasks | List all tasks for the authenticated tenant. | tasks.ts |
| DELETE | /v1/tasks/:id | Cancel (remove) a task. | tasks.ts |

### Guardrails
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/guardrails/catalog |  | guardrails.ts |
| GET    | /v1/guardrails/catalog/:checkId |  | guardrails.ts |
| GET    | /v1/guardrails/config | Get tenant guardrail pipeline config | guardrails.ts |
| PUT    | /v1/guardrails/config | Update tenant guardrail pipeline config | guardrails.ts |
| POST   | /v1/guardrails/feedback |  | guardrails.ts |
| GET    | /v1/guardrails/metrics |  | guardrails.ts |
| GET    | /v1/guardrails/pipelines |  | guardrails.ts |
| POST   | /v1/guardrails/pipelines |  | guardrails.ts |
| GET    | /v1/guardrails/pipelines/:id |  | guardrails.ts |
| PUT    | /v1/guardrails/pipelines/:id |  | guardrails.ts |
| DELETE | /v1/guardrails/pipelines/:id |  | guardrails.ts |
| POST   | /v1/guardrails/pipelines/:id/test |  | guardrails.ts |
| GET    | /v1/guardrails/providers | List available guardrail providers | guardrails.ts |
| POST   | /v1/guardrails/providers | Register external guardrail provider | guardrails.ts |
| DELETE | /v1/guardrails/providers/:id | Remove external guardrail provider | guardrails.ts |
| GET    | /v1/guardrails/templates | List well-known provider templates | guardrails.ts |
| POST   | /v1/guardrails/test | Test guardrail pipeline with sample text | guardrails.ts |

### Observability
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/observability/config | Get full broadcast config | observability.ts |
| PUT    | /v1/observability/config | Update broadcast config (enable/disable) | observability.ts |
| GET    | /v1/observability/destinations | List configured destinations | observability.ts |
| POST   | /v1/observability/destinations | Add a broadcast destination | observability.ts |
| PUT    | /v1/observability/destinations/:id | Update a destination | observability.ts |
| DELETE | /v1/observability/destinations/:id | Remove a destination | observability.ts |
| GET    | /v1/observability/templates |  | observability.ts |
| GET    | /v1/observability/templates/:provider |  | observability.ts |
| POST   | /v1/observability/test/:id | Test a destination with sample event | observability.ts |

### Governance
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/governance/agent-manifests |  | governance.ts |
| GET    | /v1/governance/agent-manifests/:agentId |  | governance.ts |
| PUT    | /v1/governance/agent-manifests/:agentId |  | governance.ts |
| DELETE | /v1/governance/agent-manifests/:agentId |  | governance.ts |
| GET    | /v1/governance/anomaly/history |  | governance.ts |
| GET    | /v1/governance/anomaly/scores |  | governance.ts |
| GET    | /v1/governance/audit/chain/verify |  | governance.ts |
| POST   | /v1/governance/audit/sign | Sign an audit entry with HMAC-SHA256 | governance.ts |
| POST   | /v1/governance/audit/verify | Verify an audit entry's HMAC integrity | governance.ts |
| GET    | /v1/governance/behavioral-profiles |  | governance.ts |
| PUT    | /v1/governance/behavioral-profiles/:role |  | governance.ts |
| DELETE | /v1/governance/behavioral-profiles/:role |  | governance.ts |
| GET    | /v1/governance/completion-audit | Completion audit trail (per-request identity + outcome) | governance.ts |
| GET    | /v1/governance/memory/audit | Memory change history (append/replace/delete/pin/evict) | governance.ts |
| GET    | /v1/governance/memory/compliance | Scan memory for policy violations | governance.ts |
| GET    | /v1/governance/memory/stats | Audit stats (operation counts by type) | governance.ts |
| POST   | /v1/governance/policy/dry-run |  | governance.ts |
| GET    | /v1/governance/sleep-time/report | Sleep-time refinement history | governance.ts |
| GET    | /v1/governance/summary | Executive dashboard (memory health + routing savings) | governance.ts |

### Providers
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/providers | Store a provider API key. | providers.ts |
| GET    | /v1/providers | List configured providers for the tenant. | providers.ts |
| DELETE | /v1/providers/:providerId | Remove a provider key by provider name. | providers.ts |
| POST   | /v1/providers/batch | Register multiple provider keys in one call. | providers.ts |
| GET    | /v1/providers/catalog | List all supported providers from the catalog | providers.ts |
| POST   | /v1/providers/test | Validate a provider API key with a lightweight live request. | providers.ts |

### MCP Gateway
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/mcp/approvals | List pending approval requests | mcp-gateway.ts |
| POST   | /v1/mcp/approvals/:id/approve | Approve a queued tool call | mcp-gateway.ts |
| POST   | /v1/mcp/approvals/:id/deny | Deny a queued tool call | mcp-gateway.ts |
| GET    | /v1/mcp/audit | Tool call audit log | mcp-gateway.ts |
| GET    | /v1/mcp/capabilities |  | mcp-gateway.ts |
| POST   | /v1/mcp/connect |  | mcp-server.ts |
| GET    | /v1/mcp/connect |  | mcp-server.ts |
| GET    | /v1/mcp/governance | Governance status | mcp-gateway.ts |
| PUT    | /v1/mcp/governance/policy | Update a tool policy | mcp-gateway.ts |
| POST   | /v1/mcp/registry |  | mcp-registry.ts |
| GET    | /v1/mcp/registry |  | mcp-registry.ts |
| DELETE | /v1/mcp/registry/:id |  | mcp-registry.ts |
| POST   | /v1/mcp/servers | Register an external MCP server | mcp-gateway.ts |
| GET    | /v1/mcp/servers | List registered servers | mcp-gateway.ts |
| GET    | /v1/mcp/servers/:id | Get server details + discovered tools | mcp-gateway.ts |
| PUT    | /v1/mcp/servers/:id | Update server config | mcp-gateway.ts |
| DELETE | /v1/mcp/servers/:id | Remove a server | mcp-gateway.ts |
| POST   | /v1/mcp/servers/:id/discover | Discover tools from a remote server | mcp-gateway.ts |
| POST   | /v1/mcp/servers/:id/health | Trigger manual health check | mcp-gateway.ts |
| GET    | /v1/mcp/servers/:id/health | Get last health status | mcp-gateway.ts |
| GET    | /v1/mcp/tools | List all tools across all servers | mcp-gateway.ts |
| POST   | /v1/mcp/tools/:server/:tool | Execute a tool call (proxied + governed) | mcp-gateway.ts |

### API Keys
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/api-keys | Create a new API key (returns plaintext once) | keys.ts |
| GET    | /v1/api-keys | List API keys (hashed, preview only) | keys.ts |
| PATCH  | /v1/api-keys/:id | Update key scopes/settings (self-service) | keys.ts |
| DELETE | /v1/api-keys/:id | Revoke an API key | keys.ts |

### Aliases
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/aliases | Read current tenant's model aliases | aliases.ts |
| PUT    | /v1/aliases | Replace the entire alias map | aliases.ts |
| PATCH  | /v1/aliases | Merge new aliases (set value to null to delete a key) | aliases.ts |

### Config
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/config | List all sections (RBAC-filtered) | config.ts |
| GET    | /v1/config/:key | Get specific section | config.ts |
| PUT    | /v1/config/:key | Replace section (full) | config.ts |
| PATCH  | /v1/config/:key | Merge-patch (RFC 7396) | config.ts |
| DELETE | /v1/config/:key | Reset to defaults (remove from DB) | config.ts |
| GET    | /v1/config/:key/audit | Audit trail for section | config.ts |
| POST   | /v1/config/import | Import from file config | config.ts |
| GET    | /v1/config/otel |  | otel-config.ts |

### Usage
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/usage/:requestId/feedback |  | usage.ts |
| GET    | /v1/usage/by-cost-center |  | usage.ts |
| GET    | /v1/usage/by-owner |  | usage.ts |
| GET    | /v1/usage/models |  | usage.ts |
| GET    | /v1/usage/spend |  | usage.ts |
| GET    | /v1/usage/summary |  | usage.ts |

### Insights
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/insights/daily |  | insights.ts |
| GET    | /v1/insights/forecast |  | insights.ts |
| GET    | /v1/insights/optimize |  | insights.ts |
| GET    | /v1/insights/waste |  | insights.ts |

### Capacity
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/capacity/forecast | Predict when rate limits/budgets will be exhausted | capacity.ts |
| GET    | /v1/capacity/providers | Per-provider capacity status and predictions | capacity.ts |

### Replays
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/replays/compare | Compare two strategies side-by-side | replays.ts |
| GET    | /v1/replays/decisions | List recorded routing decisions | replays.ts |
| POST   | /v1/replays/simulate | Simulate alternative routing on recorded traffic | replays.ts |

### Catalog
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/catalog/changes | Recent discovery events. | catalog.ts |
| POST   | /v1/catalog/refresh | Trigger immediate discovery/eviction pass. | catalog.ts |
| GET    | /v1/catalog/runnable | Models that will actually work right now. | runnable.ts |
| GET    | /v1/catalog/status | Catalog + registry status snapshot. | catalog.ts |

### Ops
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/ops/status |  | ops.ts |

### Sleep Time
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/sleep-time/config | Get sleep-time configuration. | sleep-time.ts |
| PUT    | /v1/sleep-time/config | Update sleep-time configuration. | sleep-time.ts |
| POST   | /v1/sleep-time/run | Trigger a sleep-time refinement pass. | sleep-time.ts |

### Group Mappings
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/group-mappings | List all group-role mappings for tenant | group-mappings.ts |
| GET    | /v1/group-mappings/:id | Get a single mapping | group-mappings.ts |
| PATCH  | /v1/group-mappings/:id | Update br_role and/or scopes | group-mappings.ts |
| DELETE | /v1/group-mappings/:id | Delete a mapping | group-mappings.ts |

### Agent Identity
Auth: Agent JWT or API Key

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/agent/auth/cert |  | agent-cert.ts |
| POST   | /v1/agent/auth/revoke |  | agent-cert-revoke.ts |
| GET    | /v1/agent/profiles | list (admin/operator) | agent-profiles.ts |
| POST   | /v1/agent/profiles | create (admin/operator) | agent-profiles.ts |
| GET    | /v1/agent/profiles/:agentId | read (admin/operator) | agent-profiles.ts |
| PATCH  | /v1/agent/profiles/:agentId | update (admin/operator) | agent-profiles.ts |
| DELETE | /v1/agent/profiles/:agentId | archive (admin) | agent-profiles.ts |
| GET    | /v1/agent/profiles/:agentId/delegation-graph |  | agent-profiles.ts |
| GET    | /v1/agent/profiles/:agentId/versions |  | agent-profiles.ts |
| PATCH  | /v1/agent/profiles/lifecycle/:agentId | state transition (admin/operator) | agent-profiles.ts |
| GET    | /v1/agent/profiles/me | self-read (agent role, from SPIFFE ID) | agent-profiles.ts |

### Agent Limits
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/agent-limits | Read current agent limits | agent-limits.ts |
| PUT    | /v1/agent-limits | Replace entire limits map | agent-limits.ts |
| PATCH  | /v1/agent-limits | Merge (set value to null to delete an agent's limits) | agent-limits.ts |
| GET    | /v1/agent/anomaly/me | Recent security events for calling agent. | agent-bootstrap.ts |
| POST   | /v1/agent/bootstrap | Create profile + enforce limits + issue JWT in one call. | agent-bootstrap.ts |
| POST   | /v1/agent/delegate | Parent agent creates child with sliced budget. | agent-delegate.ts |
| GET    | /v1/agent/limits/me | Budget/rate subset of status. | agent-bootstrap.ts |
| GET    | /v1/agent/reputation | returns calling agent's reputation | reputation.ts |
| GET    | /v1/agent/status | Full self-awareness: profile, limits, anomaly, governance. | agent-bootstrap.ts |
| GET    | /v1/agent/sub-agents | List caller's active children. | agent-sub-agents.ts |
| DELETE | /v1/agent/sub-agents/:child_agent_id |  | agent-sub-agents.ts |
| POST   | /v1/agent/task-runs | Report a completed task run. | task-runs.ts |
| GET    | /v1/agent/task-runs | Query run history. | task-runs.ts |
| POST   | /v1/agent/trajectories | store a trajectory | trajectories.ts |
| GET    | /v1/agent/trajectories | query trajectories (with filters) | trajectories.ts |
| GET    | /v1/agent/trajectories/export | JSONL export for training | trajectories.ts |
| GET    | /v1/agent/trajectories/stats | trajectory statistics | trajectories.ts |

### Mesh
Auth: API Key + mTLS

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/mesh/agents |  | mesh.ts |
| POST   | /v1/mesh/check |  | mesh.ts |
| POST   | /v1/mesh/deregister |  | mesh.ts |
| POST   | /v1/mesh/execute | Accept a decomposed workflow, validate DAG, | mesh-execute.ts |
| GET    | /v1/mesh/forensics |  | mesh.ts |
| GET    | /v1/mesh/forensics/:id |  | mesh.ts |
| GET    | /v1/mesh/graph |  | mesh.ts |
| GET    | /v1/mesh/graph/history |  | mesh.ts |
| POST   | /v1/mesh/heartbeat |  | mesh.ts |
| POST   | /v1/mesh/invoke/:hostname |  | mesh.ts |
| GET    | /v1/mesh/policies |  | mesh.ts |
| POST   | /v1/mesh/policies |  | mesh.ts |
| DELETE | /v1/mesh/policies/:id |  | mesh.ts |
| GET    | /v1/mesh/profiles |  | mesh.ts |
| POST   | /v1/mesh/profiles |  | mesh.ts |
| DELETE | /v1/mesh/profiles/:role |  | mesh.ts |
| POST   | /v1/mesh/register |  | mesh.ts |
| GET    | /v1/mesh/resolve/:hostname |  | mesh.ts |

### OAuth
Auth: Supabase JWT or API Key

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/oauth/apps | Register a new OAuth app. | oauth.ts |
| GET    | /v1/oauth/apps | List OAuth apps for the tenant. | oauth.ts |
| DELETE | /v1/oauth/apps/:id | Revoke an OAuth app. | oauth.ts |

### Auth (Supabase JWT)
Auth: Supabase JWT

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /auth/oauth/authorize | Authorization endpoint. | oauth.ts |
| POST   | /auth/oauth/authorize | User approves the authorization. | oauth.ts |
| POST   | /auth/oauth/token | Exchange authorization code for a scoped API key. | oauth.ts |
| GET    | /auth/workspace/files | List workspace filenames | workspace.ts |
| GET    | /auth/workspace/files/:filename{.+} |  | workspace.ts |
| PUT    | /auth/workspace/files/:filename{.+} |  | workspace.ts |
| DELETE | /auth/workspace/files/:filename{.+} |  | workspace.ts |

### SCIM Provisioning
Auth: SCIM Bearer Token

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /scim/v2/Groups |  | scim.ts |
| GET    | /scim/v2/Groups |  | scim.ts |
| GET    | /scim/v2/Groups/:id |  | scim.ts |
| PUT    | /scim/v2/Groups/:id |  | scim.ts |
| PATCH  | /scim/v2/Groups/:id |  | scim.ts |
| DELETE | /scim/v2/Groups/:id |  | scim.ts |
| GET    | /scim/v2/ResourceTypes |  | scim.ts |
| GET    | /scim/v2/Schemas |  | scim.ts |
| GET    | /scim/v2/ServiceProviderConfig |  | scim.ts |
| POST   | /scim/v2/Users |  | scim.ts |
| GET    | /scim/v2/Users |  | scim.ts |
| GET    | /scim/v2/Users/:id |  | scim.ts |
| PUT    | /scim/v2/Users/:id |  | scim.ts |
| PATCH  | /scim/v2/Users/:id |  | scim.ts |
| DELETE | /scim/v2/Users/:id |  | scim.ts |

### Other
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /.well-known/agents.json |  | server.ts |
| GET    | /events |  | auth-events.ts |
| GET    | /metrics | Prometheus-compatible metrics endpoint. | metrics.ts |
| GET    | /ops/guardian-stats | Guardian overhead, cache hit rate, anomaly count (24h) | auth-routing.ts |
| GET    | /routing/cascades | Cascade activations (model escalation on failure) | auth-routing.ts |
| GET    | /routing/decisions | Recent routing decisions with decisionTrace metadata | auth-routing.ts |
| GET    | /v1/a2a/agents |  | a2a.ts |
| POST   | /v1/a2a/certificates |  | a2a.ts |
| GET    | /v1/a2a/certificates/:agentId |  | a2a.ts |
| DELETE | /v1/a2a/certificates/:agentId |  | a2a.ts |
| POST   | /v1/a2a/discover |  | a2a.ts |
| POST   | /v1/a2a/send |  | a2a.ts |
| GET    | /v1/admin/agents/reputation | admin view of all agent reputations | reputation.ts |
| GET    | /v1/admin/digest |  | admin.ts |
| POST   | /v1/admin/invite-codes |  | admin.ts |
| GET    | /v1/admin/invite-codes |  | admin.ts |
| DELETE | /v1/admin/invite-codes/:id |  | admin.ts |
| GET    | /v1/admin/tenants |  | admin.ts |
| GET    | /v1/admin/tenants/:id |  | admin.ts |
| POST   | /v1/admin/tenants/:id/approve |  | admin.ts |
| POST   | /v1/admin/tenants/:id/reject |  | admin.ts |
| POST   | /v1/admin/tenants/:id/suspend |  | admin.ts |
| POST   | /v1/approvals/:id/approve | Approve a request | approvals.ts |
| POST   | /v1/approvals/:id/reject | Reject a request | approvals.ts |
| GET    | /v1/approvals/pending | List pending approval requests | approvals.ts |
| POST   | /v1/approvals/queue | Submit an item for human review | approvals.ts |
| POST   | /v1/audio/speech | Text-to-speech (binary audio response) | audio.ts |
| POST   | /v1/audio/transcriptions | Audio transcription (Whisper-compatible) | audio.ts |
| GET    | /v1/audit/events |  | audit-export.ts |
| GET    | /v1/audit/export |  | audit-export.ts |
| GET    | /v1/audit/retention |  | audit-export.ts |
| PUT    | /v1/audit/retention |  | audit-export.ts |
| GET    | /v1/audit/verify |  | audit-export.ts |
| POST   | /v1/auth/device/authorize | Start device authorization flow (admin scope) | identity-bridge.ts |
| POST   | /v1/auth/device/token | Poll device authorization status | identity-bridge.ts |
| POST   | /v1/auth/link | Generate a browser-based link URL | identity-bridge.ts |
| GET    | /v1/billing/plan |  | billing.ts |
| PUT    | /v1/billing/plan |  | billing.ts |
| GET    | /v1/billing/plans |  | billing.ts |
| POST   | /v1/bridge/messages | Anthropic Messages API with automatic MCP tool execution. | messages-bridge.ts |
| GET    | /v1/budget/agents |  | budget.ts |
| PUT    | /v1/budget/agents/:agentId |  | budget.ts |
| GET    | /v1/budget/alerts/config |  | budget.ts |
| PUT    | /v1/budget/alerts/config |  | budget.ts |
| GET    | /v1/budget/alerts/history |  | budget.ts |
| GET    | /v1/budget/forecast |  | budget.ts |
| PUT    | /v1/budget/limits |  | budget.ts |
| GET    | /v1/budget/status |  | budget.ts |
| POST   | /v1/compare |  | compare.ts |
| GET    | /v1/connectors | List all connectors | connectors.ts |
| POST   | /v1/connectors | Register a connector | connectors.ts |
| GET    | /v1/connectors/:id | Get a connector | connectors.ts |
| PUT    | /v1/connectors/:id | Update a connector | connectors.ts |
| DELETE | /v1/connectors/:id | Remove a connector | connectors.ts |
| POST   | /v1/connectors/:id/test | Test connector connectivity | connectors.ts |
| POST   | /v1/consensus | Multi-model consensus evaluator with optional fan-out. | consensus.ts |
| GET    | /v1/discovery | Self-describing capability discovery endpoint. | discovery.ts |
| POST   | /v1/estimate |  | estimate.ts |
| POST   | /v1/eval/datasets | Create dataset | eval-datasets.ts |
| GET    | /v1/eval/datasets | List datasets | eval-datasets.ts |
| GET    | /v1/eval/datasets/:id | Get dataset | eval-datasets.ts |
| PUT    | /v1/eval/datasets/:id | Update dataset | eval-datasets.ts |
| DELETE | /v1/eval/datasets/:id | Delete dataset + items | eval-datasets.ts |
| GET    | /v1/eval/datasets/:id/export | Export CSV/JSON | eval-datasets.ts |
| POST   | /v1/eval/datasets/:id/import-from-logs | Import from production logs | eval-datasets.ts |
| POST   | /v1/eval/datasets/:id/items | Add items (batch) | eval-datasets.ts |
| GET    | /v1/eval/datasets/:id/items | List items | eval-datasets.ts |
| DELETE | /v1/eval/datasets/:id/items/:itemId | Delete item | eval-datasets.ts |
| POST   | /v1/experiments | Create an experiment | experiments.ts |
| GET    | /v1/experiments | List experiments for tenant | experiments.ts |
| GET    | /v1/experiments/:id | Get experiment with interim results | experiments.ts |
| POST   | /v1/experiments/:id/outcomes |  | experiments.ts |
| GET    | /v1/explain/:request_id |  | explain-request.ts |
| POST   | /v1/feedback/:requestId |  | feedback.ts |
| GET    | /v1/firewall/interceptions |  | security.ts |
| GET    | /v1/fleet/insights | Top 10 models fleet summary | fleet.ts |
| POST   | /v1/forensics/export | HMAC-signed forensic export bundle | replays.ts |
| GET    | /v1/forensics/session/:sessionId/timeline | Reconstruct session timeline | replays.ts |
| POST   | /v1/god-mode/execute | execute a tool by name | god-mode.ts |
| GET    | /v1/god-mode/tools | discover BR capabilities as tools | god-mode.ts |
| GET    | /v1/health/providers | Transparent provider health (MNI v2). | provider-health.ts |
| POST   | /v1/images/generations | OpenAI-compatible image generation endpoint. | images.ts |
| POST   | /v1/intelligence/advise | Predictive Routing Intelligence. | intelligence-advise.ts |
| GET    | /v1/intelligence/benchmark |  | intelligence.ts |
| GET    | /v1/intelligence/compare |  | intelligence.ts |
| GET    | /v1/intelligence/degradation | Current degradation ladder state. | degradation.ts |
| GET    | /v1/intelligence/deprecations | Active deprecation alerts | intelligence.ts |
| GET    | /v1/intelligence/frontier |  | intelligence.ts |
| GET    | /v1/intelligence/model/:provider/:modelId | Single model profile | intelligence.ts |
| GET    | /v1/intelligence/patterns | Request pattern intelligence. | intelligence-patterns.ts |
| GET    | /v1/intelligence/rankings | Overall leaderboard | intelligence.ts |
| GET    | /v1/intelligence/savings |  | intelligence.ts |
| GET    | /v1/intelligence/status | Ingestor diagnostics | intelligence.ts |
| POST   | /v1/killswitch/activate |  | killswitch.ts |
| POST   | /v1/killswitch/deactivate |  | killswitch.ts |
| POST   | /v1/killswitch/scope |  | killswitch.ts |
| DELETE | /v1/killswitch/scope/:type/:id |  | killswitch.ts |
| GET    | /v1/killswitch/scopes |  | killswitch.ts |
| GET    | /v1/killswitch/status |  | killswitch.ts |
| POST   | /v1/messages |  | messages-bridge.ts |
| POST   | /v1/moderations | OpenAI-compatible moderation endpoint. | moderations.ts |
| POST   | /v1/onboard | One-call agent setup endpoint. | onboard.ts |
| POST   | /v1/patterns | Store a pattern (tenant-scoped) | patterns.ts |
| GET    | /v1/patterns/recommend | Get recommendations (aggregated across tenants) | patterns.ts |
| GET    | /v1/projects | List all projects (optional ?workspaceId= filter) | projects.ts |
| POST   | /v1/projects | Create a project | projects.ts |
| GET    | /v1/projects/:id | Get a project | projects.ts |
| PUT    | /v1/projects/:id | Update a project | projects.ts |
| DELETE | /v1/projects/:id | Archive a project | projects.ts |
| POST   | /v1/projects/:id/activity |  | projects.ts |
| GET    | /v1/projects/:id/activity | Get project activity | projects.ts |
| POST   | /v1/projects/:id/config | Set project configuration | projects.ts |
| GET    | /v1/projects/:id/config | Get project configuration | projects.ts |
| GET    | /v1/projects/registry | List all registered projects for tenant. | projects-registry.ts |
| POST   | /v1/projects/registry | Register/sync a project (upsert by name). | projects-registry.ts |
| GET    | /v1/projects/registry/:name | Get a single project by name. | projects-registry.ts |
| PUT    | /v1/projects/registry/:name | Update project metadata. | projects-registry.ts |
| GET    | /v1/rbac/my-permissions | returns the caller's roles, permissions, | rbac-introspection.ts |
| POST   | /v1/recommend | Model recommendation advisory endpoint. | recommend.ts |
| POST   | /v1/register | Create tenant + admin user + API key in one atomic transaction. | register.ts |
| POST   | /v1/route |  | routing.ts |
| POST   | /v1/routing/canary |  | canary.ts |
| GET    | /v1/routing/canary |  | canary.ts |
| DELETE | /v1/routing/canary |  | canary.ts |
| GET    | /v1/routing/canary/results |  | canary.ts |
| GET    | /v1/security/anomalies | recent anomaly alerts | security.ts |
| GET    | /v1/security/anomalies/baselines | export anomaly baselines | security.ts |
| POST   | /v1/security/anomalies/baselines | import anomaly baselines | security.ts |
| GET    | /v1/security/anomalies/stats/:entityType/:entityId/:metric |  | security.ts |
| GET    | /v1/security/owasp-coverage |  | owasp-coverage.ts |
| GET    | /v1/security/owasp-items |  | owasp-coverage.ts |
| GET    | /v1/security/policies | get current policy ruleset | security.ts |
| PUT    | /v1/security/policies | update policy ruleset | security.ts |
| GET    | /v1/security/policies/presets | list built-in policy presets | security.ts |
| POST   | /v1/security/policies/test | test a context against policies | security.ts |
| POST   | /v1/security/red-team |  | red-team.ts |
| GET    | /v1/security/red-team |  | red-team.ts |
| GET    | /v1/security/red-team/:id |  | red-team.ts |
| GET    | /v1/security/red-team/categories |  | red-team.ts |
| GET    | /v1/security/shadow-ai/alerts |  | shadow-ai.ts |
| POST   | /v1/security/shadow-ai/alerts/:id/ack |  | shadow-ai.ts |
| POST   | /v1/security/shadow-ai/reset-baseline |  | shadow-ai.ts |
| GET    | /v1/security/shadow-ai/scan-config |  | shadow-ai.ts |
| POST   | /v1/security/shadow-ai/scan-config |  | shadow-ai.ts |
| POST   | /v1/security/shadow-ai/scan-now |  | shadow-ai.ts |
| GET    | /v1/security/shadow-ai/scans/:id |  | shadow-ai.ts |
| GET    | /v1/security/shadow-ai/summary |  | shadow-ai.ts |
| GET    | /v1/security/siem | get SIEM config | security.ts |
| PUT    | /v1/security/siem | set SIEM config | security.ts |
| GET    | /v1/security/status | overall security status | security.ts |
| GET    | /v1/self | Agent self-awareness megaendpoint (MNI v2). | self.ts |
| POST   | /v1/sessions/:id/state | Save session state (upsert) | sessions-state.ts |
| GET    | /v1/sessions/latest | Get most recent session for a project | sessions-state.ts |
| GET    | /v1/telemetry/live |  | telemetry.ts |
| POST   | /v1/tenant/claim-link | Generate a claim link (admin scope) | identity-bridge.ts |
| GET    | /v1/workflows | list workflow definitions | workflow.ts |
| POST   | /v1/workflows | create workflow definition | workflow.ts |
| GET    | /v1/workflows/:id | get workflow definition | workflow.ts |
| DELETE | /v1/workflows/:id | delete workflow definition | workflow.ts |
| POST   | /v1/workflows/auto-select | auto-select preset from NL description | workflow.ts |
| GET    | /v1/workflows/presets | list available presets | workflow.ts |
| POST   | /v1/workflows/run | start a workflow run (SSE stream) | workflow.ts |
| GET    | /v1/workflows/runs | list runs | workflow.ts |
| GET    | /v1/workflows/runs/:id | get run details | workflow.ts |
| POST   | /v1/workflows/runs/:id/cancel | cancel a run | workflow.ts |
| GET    | /v1/workspaces | List all workspaces | workspaces.ts |
| POST   | /v1/workspaces | Create a workspace | workspaces.ts |
| GET    | /v1/workspaces/:id | Get a workspace | workspaces.ts |
| PUT    | /v1/workspaces/:id | Update a workspace | workspaces.ts |
| DELETE | /v1/workspaces/:id | Archive a workspace | workspaces.ts |
| POST   | /webhooks/slack/action |  | admin.ts |

---

## Examples

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

### List Models
```bash
curl https://api.brainstormrouter.com/v1/models \
  -H "Authorization: Bearer brk_your_key"
```

### Query Memory
```bash
curl -X POST https://api.brainstormrouter.com/v1/memory/query \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were the key decisions from yesterday?",
    "blocks": ["human", "system", "project", "general"],
    "limit": 10
  }'
```

### Create Provider Key
```bash
curl -X POST https://api.brainstormrouter.com/v1/providers \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "label": "Production",
    "apiKey": "sk-ant-..."
  }'
```

### Test Guardrail
```bash
curl -X POST https://api.brainstormrouter.com/v1/guardrails/test \
  -H "Authorization: Bearer brk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Test message for PII detection",
    "direction": "inbound"
  }'
```

---

## SDKs

### TypeScript
```bash
npm install brainstormrouter
```
```typescript
import { BrainstormRouter } from "brainstormrouter";
const br = new BrainstormRouter({ apiKey: "brk_..." });
const result = await br.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello" }],
});
```

### Python
```bash
pip install brainstormrouter
```
```python
from brainstormrouter import BrainstormRouter
br = BrainstormRouter(api_key="brk_...")
result = br.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
)
```

---

## MCP Server

Endpoint: `POST https://api.brainstormrouter.com/v1/mcp/connect`
Transport: Streamable HTTP

Available tools:
- `br_route_completion` — Route a chat completion through the engine
- `br_list_models` — List available model endpoints
- `br_get_usage` — Get usage summary for a period
- `br_set_alias` — Create or update a model alias
- `br_get_health` — Check API health status

---

Total routes: 416