# BrainstormRouter — Complete API Reference

> Autonomous AI API Engine — intelligent routing across a curated catalog of
> 31 models from 8 providers (Anthropic, OpenAI, Google, xAI, Groq, Perplexity,
> DeepSeek, Moonshot) 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 br_live_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 | Liveness probe — returns ok while the process is up and serving HTTP | capabilities/system.health |
| GET    | /health/ready |  | 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 | Initiate signup: send 6-digit verification code to email | capabilities/system.signup.start |
| POST   | /v1/signup/verify | Verify code → create tenant + user + API key atomically | capabilities/system.signup.verify |
| GET    | /v1/tos | Returns current Terms of Service version, summary, and URL | capabilities/system.tos |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/account | Get tenant profile with user count | capabilities/system.account.get |
| PATCH  | /v1/account | Update tenant profile (currently: name) | capabilities/system.account.update |
| GET    | /v1/account/users | List users in the current tenant (RLS-scoped) | capabilities/system.account.users.list |
| DELETE | /v1/account/users/{id} | Remove a user from the current tenant | capabilities/system.account.users.remove |
| POST   | /v1/account/users/invite | Invite a user by email; returns claim URL (201) | capabilities/system.account.users.invite |

### Webhooks
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/webhooks | Create a webhook subscription (returns secret once); 400 on SSRF-blocked URL | capabilities/system.webhooks.create |
| GET    | /v1/webhooks | List webhook subscriptions for the current tenant | capabilities/system.webhooks.list |
| DELETE | /v1/webhooks/{id} | Delete a webhook by ID (404 on missing) | capabilities/system.webhooks.delete |
| PATCH  | /v1/webhooks/{id} | Update webhook URL/events/is_active (400 SSRF, 404 missing) | capabilities/system.webhooks.update |
| GET    | /v1/webhooks/{id}/deliveries | Recent delivery history for a webhook (last 50) | capabilities/system.webhooks.deliveries |
| POST   | /v1/webhooks/{id}/test | Send a test event to a webhook; records delivery row regardless of outcome | capabilities/system.webhooks.test |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/chat/completions | OpenAI-compatible chat completions — streaming + non-streaming, full ModelRouter pipeline (Thompson sampling, cascade, validity, budget commit) | capabilities/completions.create |
| POST   | /v1/embeddings | OpenAI-compatible embeddings endpoint (routed through BR provider catalog) | capabilities/embeddings.create |

### Models
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/models | List available models for the authenticated tenant (auto-detects OpenAI vs Anthropic format) | capabilities/system.models.list |
| GET    | /v1/models/{provider}/{modelId}/capabilities | Per-model capability profile: catalog flags + production quality/latency/success metrics | capabilities/system.models.capabilities |
| GET    | /v1/models/leaderboard | Per-model performance rankings across reward, quality, speed, value, reliability | capabilities/system.models_leaderboard |

### Memory
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/memory/approval-config | Get the memory-write approval-required flag | capabilities/system.memory.approvalConfig.get |
| PUT    | /v1/memory/approval-config | Set the memory-write approval-required flag | capabilities/system.memory.approvalConfig.set |
| GET    | /v1/memory/blocks | List memory blocks with entry counts (optional ?project= filter) | capabilities/system.memory.blocks.list |
| GET    | /v1/memory/blocks/{block} | List entries in a specific memory block | capabilities/system.memory.blocks.get |
| POST   | /v1/memory/blocks/sync | Bulk upsert core memory entries for a project (Brainstorm CLI) | capabilities/system.memory.blocks.sync |
| POST   | /v1/memory/entries | Append a new core memory entry (alias for /v1/memory/store) | capabilities/system.memory.entries.create |
| GET    | /v1/memory/entries | List all core memory entries (optional ?project= filter) | capabilities/system.memory.entries.list |
| DELETE | /v1/memory/entries/{id} | Delete a memory entry | capabilities/system.memory.entries.delete |
| PUT    | /v1/memory/entries/{id} | Update fact text and/or pin state for an entry | capabilities/system.memory.entries.update |
| POST   | /v1/memory/init | Bootstrap memory from context documents via LLM extraction | capabilities/system.memory.init |
| GET    | /v1/memory/pending | List pending memory writes (unified queue + legacy) | capabilities/system.memory.pending.list |
| POST   | /v1/memory/pending/{id}/approve | Approve a pending memory write (unified queue or legacy) | capabilities/system.memory.pending.approve |
| POST   | /v1/memory/pending/{id}/reject | Reject a pending memory write | capabilities/system.memory.pending.reject |
| POST   | /v1/memory/query | Relevance-scored memory query (top-N matches) | capabilities/system.memory.query |
| GET    | /v1/memory/shared/entries | List shared memory entries plus pending approval count | capabilities/system.memory.shared.list |
| POST   | /v1/memory/shared/store | Store a tenant-wide shared memory entry (may queue for approval) | capabilities/system.memory.shared.store |
| POST   | /v1/memory/store | Append a core memory entry (canonical path) | capabilities/system.memory.store |

### Prompts
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/prompts | Create a versioned prompt template | capabilities/system.prompts.create |
| GET    | /v1/prompts | List all prompt templates for the tenant | capabilities/system.prompts.list |
| DELETE | /v1/prompts/{id} | Archive a prompt template (soft delete) | capabilities/system.prompts.archive |
| GET    | /v1/prompts/{id} | Get a prompt template with its full version history | capabilities/system.prompts.get |
| PUT    | /v1/prompts/{id} | Update a prompt — auto-creates a new version | capabilities/system.prompts.update |
| GET    | /v1/prompts/{id}/ab | Get A/B test results for a prompt | capabilities/system.prompts.ab.get |
| POST   | /v1/prompts/{id}/ab | Start or stop an A/B test for a prompt | capabilities/system.prompts.ab.set |
| GET    | /v1/prompts/{id}/diff | Unified diff between two versions of a prompt | capabilities/system.prompts.diff |
| POST   | /v1/prompts/{id}/evaluate | Run a prompt against test cases with a chosen scorer | capabilities/system.prompts.evaluate |
| GET    | /v1/prompts/{id}/evaluate/results | List recent evaluation runs for a prompt with aggregate metrics | capabilities/system.prompts.evalResults |
| GET    | /v1/prompts/{id}/evaluate/results/{runId}/export | Export a single evaluation run as JSON or CSV | capabilities/system.prompts.evalExport |
| POST   | /v1/prompts/{id}/promote | Promote a prompt version to a higher environment | capabilities/system.prompts.promote |
| POST   | /v1/prompts/{id}/test | Test-resolve a prompt template with the given variables | capabilities/system.prompts.test |

### Presets
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/presets | Create a routing preset (saved `@preset/<slug>` configuration) | capabilities/system.presets.create |
| GET    | /v1/presets | List active routing presets for the tenant | capabilities/system.presets.list |
| DELETE | /v1/presets/{slug} | Archive a routing preset (soft-delete) | capabilities/system.presets.archive |
| GET    | /v1/presets/{slug} | Get a routing preset by slug | capabilities/system.presets.get |
| PUT    | /v1/presets/{slug} | Update a routing preset (partial) | capabilities/system.presets.update |

### Tasks
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/tasks | Schedule a background agent task (cron-scheduled prompt) | capabilities/system.tasks.create |
| GET    | /v1/tasks | List all background tasks for the tenant | capabilities/system.tasks.list |
| DELETE | /v1/tasks/{id} | Cancel a scheduled background task | capabilities/system.tasks.delete |

### Guardrails
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/guardrails/catalog | List checks in the V2 guardrail registry | capabilities/system.guardrails.catalog.list |
| GET    | /v1/guardrails/catalog/{checkId} | Get a single check definition | capabilities/system.guardrails.catalog.get |
| GET    | /v1/guardrails/config | Get the tenant guardrail pipeline config | capabilities/system.guardrails.config.get |
| PUT    | /v1/guardrails/config | Update the tenant guardrail pipeline config | capabilities/system.guardrails.config.set |
| POST   | /v1/guardrails/feedback | Submit false-positive / true-positive feedback for a guardrail scan | capabilities/system.guardrails.feedback |
| GET    | /v1/guardrails/metrics | Aggregated scan + feedback metrics (security_events or in-memory) | capabilities/system.guardrails.metrics |
| POST   | /v1/guardrails/pipelines | Create a V2 guardrail pipeline | capabilities/system.guardrails.pipelines.create |
| GET    | /v1/guardrails/pipelines | List tenant V2 guardrail pipelines | capabilities/system.guardrails.pipelines.list |
| DELETE | /v1/guardrails/pipelines/{id} | Delete a V2 guardrail pipeline | capabilities/system.guardrails.pipelines.delete |
| GET    | /v1/guardrails/pipelines/{id} | Get a V2 guardrail pipeline by id | capabilities/system.guardrails.pipelines.get |
| PUT    | /v1/guardrails/pipelines/{id} | Update a V2 guardrail pipeline | capabilities/system.guardrails.pipelines.update |
| POST   | /v1/guardrails/pipelines/{id}/test | Test a V2 guardrail pipeline against sample text | capabilities/system.guardrails.pipelines.test |
| POST   | /v1/guardrails/providers | Register an external guardrail provider | capabilities/system.guardrails.providers.create |
| GET    | /v1/guardrails/providers | List built-in + external guardrail providers | capabilities/system.guardrails.providers.list |
| DELETE | /v1/guardrails/providers/{id} | Remove an external guardrail provider | capabilities/system.guardrails.providers.delete |
| GET    | /v1/guardrails/templates | List well-known provider templates | capabilities/system.guardrails.templates.list |
| POST   | /v1/guardrails/test | Run text through the guardrail pipeline (testing/preview) | capabilities/system.guardrails.test |

### Observability
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/observability/config | Get the full broadcast config (enabled + destinations) | capabilities/system.observability.getConfig |
| PUT    | /v1/observability/config | Enable or disable broadcasting for the tenant | capabilities/system.observability.updateConfig |
| POST   | /v1/observability/destinations | Add a broadcast destination | capabilities/system.observability.addDestination |
| GET    | /v1/observability/destinations | List configured broadcast destinations for the tenant | capabilities/system.observability.listDestinations |
| DELETE | /v1/observability/destinations/{id} | Remove a broadcast destination | capabilities/system.observability.deleteDestination |
| PUT    | /v1/observability/destinations/{id} | Update a broadcast destination | capabilities/system.observability.updateDestination |
| GET    | /v1/observability/templates | List available integration template names | capabilities/system.observability.listTemplates |
| GET    | /v1/observability/templates/{provider} | Get a single integration template (config schema + example) | capabilities/system.observability.getTemplate |
| POST   | /v1/observability/test/{id} | Send a synthetic event to verify a destination is reachable | capabilities/system.observability.testDestination |
| POST   | /v1/observability/xdr/destinations | Register a new XDR/SIEM destination | capabilities/system.xdr.create |
| GET    | /v1/observability/xdr/destinations | List XDR/SIEM destinations for the tenant | capabilities/system.xdr.list |
| DELETE | /v1/observability/xdr/destinations/{id} | Remove an XDR/SIEM destination | capabilities/system.xdr.delete |
| PUT    | /v1/observability/xdr/destinations/{id} | Update an XDR/SIEM destination (partial) | capabilities/system.xdr.update |
| POST   | /v1/observability/xdr/destinations/{id}/enable | Toggle an XDR destination on/off | capabilities/system.xdr.enable |
| GET    | /v1/observability/xdr/destinations/{id}/stats | Get delivery stats for an XDR destination | capabilities/system.xdr.stats |
| POST   | /v1/observability/xdr/destinations/{id}/test | Send a synthetic test event to a destination | capabilities/system.xdr.test |

### Governance
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/governance/agent-manifests | List agent manifests (CAF Phase 2 semantic RBAC) | capabilities/system.governance.agentManifests.list |
| DELETE | /v1/governance/agent-manifests/{agentId} | Delete an agent manifest | capabilities/system.governance.agentManifests.delete |
| GET    | /v1/governance/agent-manifests/{agentId} | Get an agent manifest by agent id | capabilities/system.governance.agentManifests.get |
| PUT    | /v1/governance/agent-manifests/{agentId} | Create or replace an agent manifest | capabilities/system.governance.agentManifests.upsert |
| GET    | /v1/governance/anomaly/history | Anomaly history (last N events) | capabilities/system.governance.anomaly.history |
| GET    | /v1/governance/anomaly/scores | Recent anomaly-detected security events | capabilities/system.governance.anomaly.scores |
| GET    | /v1/governance/audit/chain/verify | Verify the hash-chain integrity of the completion audit trail | capabilities/system.governance.audit.chainVerify |
| POST   | /v1/governance/audit/sign | Sign an audit entry with HMAC-SHA256 (tenant-scoped) | capabilities/system.governance.audit.sign |
| POST   | /v1/governance/audit/verify | Verify an audit entry's HMAC integrity | capabilities/system.governance.audit.verify |
| GET    | /v1/governance/behavioral-profiles | List behavioral profiles (CAF Phase 2) | capabilities/system.governance.behavioralProfiles.list |
| DELETE | /v1/governance/behavioral-profiles/{role} | Delete a behavioral profile by role | capabilities/system.governance.behavioralProfiles.delete |
| PUT    | /v1/governance/behavioral-profiles/{role} | Create or replace a behavioral profile for a role | capabilities/system.governance.behavioralProfiles.upsert |
| GET    | /v1/governance/completion-audit | Completion audit trail (per-request identity + outcome) | capabilities/system.governance.completionAudit |
| GET    | /v1/governance/compliance/autopilot | Regulatory compliance autopilot (frameworks + score) | capabilities/system.governance.compliance.autopilot |
| GET    | /v1/governance/compliance/eu-ai-act | Generate an EU AI Act compliance report | capabilities/system.governance.compliance.euAiAct |
| POST   | /v1/governance/credentials/issue | Issue a verifiable agent credential (VAC) | capabilities/system.governance.credentials.issue |
| POST   | /v1/governance/credentials/verify | Verify a credential signature and compute trust level | capabilities/system.governance.credentials.verify |
| POST   | /v1/governance/knowledge/snapshot | Create a knowledge-escrow snapshot for an agent | capabilities/system.governance.knowledge.snapshot |
| GET    | /v1/governance/lineage | Decision lineage — durable trace reconstruction (or ?live=true ring buffer) | capabilities/system.governance.lineage |
| GET    | /v1/governance/lineage/{request_id} | The WHY answer for one request — verified audit block + policy_context + lineage | capabilities/system.governance.lineage.get |
| GET    | /v1/governance/memory/audit | Memory change history (append/replace/delete/pin/evict) | capabilities/system.governance.memory.audit |
| GET    | /v1/governance/memory/compliance | Scan core memory for PII/policy violations | capabilities/system.governance.memory.compliance |
| GET    | /v1/governance/memory/reconstruct | Reconstruct memory state at a past timestamp (with optional diff) | capabilities/system.governance.memory.reconstruct |
| GET    | /v1/governance/memory/stats | Memory audit stats (operation counts by type) | capabilities/system.governance.memory.stats |
| POST   | /v1/governance/policy/dry-run | Evaluate a PolicyContext against the tenant ruleset (no enforcement) | capabilities/system.governance.policy.dryRun |
| GET    | /v1/governance/sleep-time/report | Sleep-time refinement history | capabilities/system.governance.sleepTimeReport |
| POST   | /v1/governance/sovereignty/policy | Create a clean-room sovereignty policy between two orgs | capabilities/system.governance.sovereignty.policy |
| POST   | /v1/governance/sovereignty/purge | Issue a provable purge of memory entries for an org | capabilities/system.governance.sovereignty.purge |
| GET    | /v1/governance/summary | Executive dashboard summary (memory health + activity) | capabilities/system.governance.summary |

### Providers
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/providers | List configured providers for the tenant (admin/operator only) | capabilities/system.providers.list |
| POST   | /v1/providers | Store an encrypted provider API key for the tenant | capabilities/system.providers.register |
| DELETE | /v1/providers/{providerId} | Remove a provider key by provider name | capabilities/system.providers.delete |
| POST   | /v1/providers/batch | Register up to 10 provider keys in one call (returns 207) | capabilities/system.providers.batch |
| GET    | /v1/providers/catalog | Public catalog of supported provider IDs and base URLs | capabilities/system.providers.catalog |
| POST   | /v1/providers/test | Validate a provider API key with a lightweight live request | capabilities/system.providers.test |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/mcp/approvals | List pending MCP tool-call approvals | capabilities/system.mcp.governance.approvalsList |
| POST   | /v1/mcp/approvals/{id}/approve | Approve a queued MCP tool call | capabilities/system.mcp.governance.approve |
| POST   | /v1/mcp/approvals/{id}/deny | Deny a queued MCP tool call | capabilities/system.mcp.governance.deny |
| GET    | /v1/mcp/audit | Recent MCP tool-call audit entries for the tenant | capabilities/system.mcp.audit |
| GET    | /v1/mcp/capabilities | Core + external MCP tool catalog for the tenant | capabilities/system.mcp.capabilities |
| POST   | /v1/mcp/connect | Open an MCP Streamable HTTP session against BR's control-plane tools | capabilities/system.mcp.connect |
| GET    | /v1/mcp/connect | MCP server discovery (capability + tool manifest) | capabilities/system.mcp.discover |
| GET    | /v1/mcp/governance | Get MCP governance engine status | capabilities/system.mcp.governance.status |
| PUT    | /v1/mcp/governance/policy | Update an MCP tool-name policy in the governance engine | capabilities/system.mcp.governance.updatePolicy |
| GET    | /v1/mcp/registry | List MCP servers registered for the current tenant | capabilities/security.mcp_registry.list |
| POST   | /v1/mcp/registry | Register a trusted MCP server for the current tenant | capabilities/security.mcp_registry.register |
| DELETE | /v1/mcp/registry/{id} | Remove an MCP server from the tenant's registry | capabilities/security.mcp_registry.remove |
| POST   | /v1/mcp/servers | Register an external MCP server for this tenant | capabilities/system.mcp.servers.create |
| GET    | /v1/mcp/servers | List registered MCP servers for this tenant | capabilities/system.mcp.servers.list |
| DELETE | /v1/mcp/servers/{id} | Remove an MCP server registration | capabilities/system.mcp.servers.delete |
| GET    | /v1/mcp/servers/{id} | Get details for an MCP server | capabilities/system.mcp.servers.get |
| PUT    | /v1/mcp/servers/{id} | Update an MCP server registration | capabilities/system.mcp.servers.update |
| POST   | /v1/mcp/servers/{id}/discover | Trigger remote tool discovery for an MCP server | capabilities/system.mcp.servers.discover |
| POST   | /v1/mcp/servers/{id}/health | Trigger an on-demand health check for an MCP server | capabilities/system.mcp.servers.healthCheck |
| GET    | /v1/mcp/servers/{id}/health | Get the last health status for an MCP server | capabilities/system.mcp.servers.healthGet |
| GET    | /v1/mcp/tools | List all discovered tools across registered MCP servers | capabilities/system.mcp.tools.list |
| POST   | /v1/mcp/tools/{server}/{tool} | Execute a tool call through the MCP gateway (proxied + governed) | capabilities/system.mcp.tools.call |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/api-keys | Create a new API key (plaintext returned once) | capabilities/system.api_keys.create |
| GET    | /v1/api-keys | List API keys (no plaintext, preview only) | capabilities/system.api_keys.list |
| DELETE | /v1/api-keys/{id} | Revoke an API key (soft-delete; cache invalidated immediately) | capabilities/system.api_keys.revoke |
| PATCH  | /v1/api-keys/{id} | Update an API key's scopes, limits, or metadata (self-service) | capabilities/system.api_keys.update |

### Aliases
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/aliases | Read the model alias map for the current tenant | capabilities/system.aliases.get |
| PATCH  | /v1/aliases | Merge alias updates (null value deletes a key) | capabilities/system.aliases.patch |
| PUT    | /v1/aliases | Replace the entire model alias map (rejects null values; use PATCH to delete) | capabilities/system.aliases.put |

### Config
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/config | List all config sections (RBAC-filtered, sensitive fields redacted for non-admins) | capabilities/system.config.list |
| DELETE | /v1/config/{key} | Delete a config section (reset to defaults) | capabilities/system.config.delete |
| GET    | /v1/config/{key} | Read a single config section (sensitive fields redacted for non-admins) | capabilities/system.config.get |
| PATCH  | /v1/config/{key} | Merge-patch a config section (RFC 7396) with optional OCC | capabilities/system.config.patch |
| PUT    | /v1/config/{key} | Replace a config section (full PUT) with OCC via If-Match header | capabilities/system.config.set |
| GET    | /v1/config/{key}/audit | Audit trail (recent change events) for a config section | capabilities/system.config.audit |
| POST   | /v1/config/import | Import configuration sections from the on-disk file (admin only) | capabilities/system.config.import |
| GET    | /v1/config/otel | OpenTelemetry exporter configuration: endpoint, service name, batching | capabilities/system.config.otel |

### Usage
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/usage/{requestId}/feedback | Submit quality feedback for a specific request | capabilities/system.usage.feedback |
| GET    | /v1/usage/by-cost-center | Aggregated spend per cost center for the period | capabilities/system.usage.by_cost_center |
| GET    | /v1/usage/by-owner | Aggregated spend per agent owner for the period | capabilities/system.usage.by_owner |
| GET    | /v1/usage/models | Per-model usage breakdown for the current period | capabilities/system.usage.models |
| GET    | /v1/usage/spend | Total spend for the current billing period | capabilities/system.usage.spend |
| GET    | /v1/usage/summary | Spend, request count, latency summary for the current period | capabilities/system.usage.summary |

### Insights
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/insights/daily | Daily cost-optimization insight rollup (requires DB) | capabilities/system.insights.daily |
| GET    | /v1/insights/forecast | Budget runway forecast (daily or monthly period) | capabilities/system.insights.forecast |
| GET    | /v1/insights/optimize | Model-substitution recommendations for cost reduction | capabilities/system.insights.optimize |
| GET    | /v1/insights/waste | Waste detection report. Returns 403 privacy_restricted on strict privacy mode. | capabilities/system.insights.waste |

### Capacity
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/capacity/forecast | Predict rate-limit exhaustion + budget burn per provider (DB-backed forecast) | capabilities/system.capacity.forecast |
| GET    | /v1/capacity/providers | Per-provider capacity status (24h) — request count, success rate, latency, cost, health | capabilities/system.capacity.providers |

### Replays
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/replays/compare | Compare routing strategies side-by-side on recorded traffic | capabilities/system.replays.compare |
| GET    | /v1/replays/decisions | List recorded routing decisions for the tenant | capabilities/system.replays.decisions |
| POST   | /v1/replays/simulate | Simulate alternative routing strategy on recorded traffic | capabilities/system.replays.simulate |

### Catalog
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/catalog/runnable | Filtered list of models routable right now (circuit-closed + sentinel-healthy + BYOK-keyed) | capabilities/system.catalog.runnable |
| GET    | /v1/catalog/status | Curated-catalog status: total endpoints, models, per-provider counts | capabilities/system.catalog.status |

### Ops
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/ops/build | Authenticated runtime build identity for evidence-gated production verification | capabilities/system.ops.build |
| POST   | /v1/ops/circuit/reset | Manually reset circuit breakers (endpoint, provider, or all). Admin-only. | capabilities/system.ops.circuit.reset |
| POST   | /v1/ops/diagnose | Run provider-doctor against the fleet; returns structured diagnoses + remediations | capabilities/system.ops.diagnose |
| GET    | /v1/ops/guardian-stats | Guardian overhead, cache hit rate, anomaly count (24h) | capabilities/intelligence.ops.guardian_stats |
| GET    | /v1/ops/status | Single-pane-of-glass status: providers, endpoints, budget, usage | capabilities/system.ops.status |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/sleep-time/config | Get the tenant's sleep-time refinement configuration | capabilities/system.sleep_time.config.get |
| PUT    | /v1/sleep-time/config | Update the tenant's sleep-time refinement configuration | capabilities/system.sleep_time.config.set |
| POST   | /v1/sleep-time/run | Trigger an immediate sleep-time memory refinement pass | capabilities/system.sleep_time.run |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/group-mappings | List IdP group → RBAC role mappings for the tenant | capabilities/system.group_mappings.list |
| DELETE | /v1/group-mappings/{id} | Delete an IdP group → role mapping | capabilities/system.group_mappings.delete |
| GET    | /v1/group-mappings/{id} | Get a single group → role mapping by ID | capabilities/system.group_mappings.get |
| PATCH  | /v1/group-mappings/{id} | Update an IdP group mapping's role, scopes, or display name | capabilities/system.group_mappings.update |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/agent/auth/cert | Exchange agent JWT + CSR for a signed mTLS client certificate | capabilities/security.agent.cert_issue |
| POST   | /v1/agent/auth/revoke | Revoke an agent certificate (single by serial, or bulk per tenant) | capabilities/security.agent.cert_revoke |
| POST   | /v1/agent/profiles | Create a new agent profile (admin/operator) | capabilities/security.agent_profiles.create |
| GET    | /v1/agent/profiles | List all agent profiles for the tenant | capabilities/security.agent_profiles.list |
| DELETE | /v1/agent/profiles/{agentId} | Archive (soft-delete) an agent profile | capabilities/security.agent_profiles.archive |
| GET    | /v1/agent/profiles/{agentId} | Read a single agent profile by id | capabilities/security.agent_profiles.get |
| PATCH  | /v1/agent/profiles/{agentId} | Update an agent profile (admin/operator) | capabilities/security.agent_profiles.update |
| GET    | /v1/agent/profiles/{agentId}/delegation-graph | Return the parent/child delegation graph for an agent | capabilities/security.agent_profiles.delegation_graph |
| GET    | /v1/agent/profiles/{agentId}/versions | Return up to 10 historical snapshots of an agent profile | capabilities/security.agent_profiles.versions |
| PATCH  | /v1/agent/profiles/lifecycle/{agentId} | Transition an agent profile to a target lifecycle state | capabilities/security.agent_profiles.lifecycle |
| GET    | /v1/agent/profiles/me | Self-read agent profile (uses _agentIdentity) | capabilities/security.agent_profiles.self |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/agent-limits | Read the per-agent limits map for the current tenant | capabilities/system.agent_limits.get |
| PATCH  | /v1/agent-limits | Merge updates into the per-agent limits map (null value deletes an entry) | capabilities/system.agent_limits.patch |
| PUT    | /v1/agent-limits | Replace the entire per-agent limits map (canonicalizes keys to `agent:<id>`) | capabilities/system.agent_limits.put |
| GET    | /v1/agent/anomaly/me | Recent security events for the calling agent | capabilities/security.agent.anomaly.me |
| POST   | /v1/agent/bootstrap | Zero-human agent onboarding — profile + enforced limits + JWT | capabilities/security.agent.bootstrap |
| POST   | /v1/agent/delegate | Parent agent creates a child agent with sliced budget (agent-JWT only) | capabilities/security.agent.delegate |
| POST   | /v1/agent/federated-bootstrap | Federated agent bootstrap — external IDP JWT → BR session JWT | capabilities/security.agent.federated_bootstrap |
| GET    | /v1/agent/limits/me | Budget + rate-limit state for the calling agent | capabilities/security.agent.limits.me |
| GET    | /v1/agent/reputation | Caller's own agent reputation: score, tier, and tier multipliers | capabilities/intelligence.reputation.self |
| GET    | /v1/agent/status | Full self-awareness: profile, limits, anomaly, governance | capabilities/security.agent.status |
| GET    | /v1/agent/sub-agents | List sub-agents (children) of the calling agent | capabilities/security.agent.sub_agents.list |
| DELETE | /v1/agent/sub-agents/{child_agent_id} | Terminate a sub-agent and reclaim its budget (caller must be parent) | capabilities/security.agent.sub_agents.terminate |
| GET    | /v1/agent/task-runs | Query task-run history (filter by project, limit) | capabilities/system.task_runs.query |
| POST   | /v1/agent/task-runs | Report a completed task run (Brainstorm CLI integration; 201) | capabilities/system.task_runs.report |
| GET    | /v1/agent/trajectories | Query stored trajectories with filters (project, request_type, source, limit, since) | capabilities/intelligence.trajectories.query |
| POST   | /v1/agent/trajectories | Record an orchestration trajectory for the current tenant | capabilities/intelligence.trajectories.record |
| GET    | /v1/agent/trajectories/export | Export trajectories as JSONL for offline training pipelines | capabilities/intelligence.trajectories.export |
| GET    | /v1/agent/trajectories/stats | Aggregate statistics over stored trajectories for the current tenant | capabilities/intelligence.trajectories.stats |
| POST   | /v1/agents/{agentId}/run | Start the agent loop for a session and stream events as SSE | capabilities/system.agents.run |
| GET    | /v1/agents/{agentId}/runs | Run history for an agent (sessions with aggregate metadata) | capabilities/system.agents.runs.list |
| POST   | /v1/agents/{agentId}/sessions | Create an idle session for the agent (no loop) | capabilities/system.agents.sessions.create |
| GET    | /v1/agents/{agentId}/sessions/{sessionId} | Get a session by id | capabilities/system.agents.sessions.get |
| DELETE | /v1/agents/{agentId}/sessions/{sessionId} | Terminate a session (status → ended) | capabilities/system.agents.sessions.terminate |
| POST   | /v1/agents/{agentId}/sessions/{sessionId}/events | Publish a user event to a running session (PG NOTIFY) | capabilities/system.agents.sessions.sendEvent |

### Mesh
Auth: API Key + mTLS

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /v1/mesh/agents | List registered agents in the mesh for this tenant | capabilities/system.mesh.agents.list |
| POST   | /v1/mesh/check | Evaluate a mesh access decision for source → destination | capabilities/system.mesh.check |
| POST   | /v1/mesh/deregister | Deregister an agent from the mesh (mTLS required) | capabilities/system.mesh.deregister |
| POST   | /v1/mesh/execute | Run a DAG-based mesh workflow, streaming step progress as SSE | capabilities/system.mesh.execute |
| GET    | /v1/mesh/forensics | List forensic snapshots for the tenant | capabilities/system.mesh.forensics.list |
| GET    | /v1/mesh/forensics/{id} | Get a single forensic snapshot by id | capabilities/system.mesh.forensics.get |
| GET    | /v1/mesh/graph | Current mesh graph snapshot for this tenant | capabilities/system.mesh.graph |
| GET    | /v1/mesh/graph/history | Historical mesh graph snapshots over the last N hours | capabilities/system.mesh.graph.history |
| POST   | /v1/mesh/heartbeat | Send a liveness heartbeat for the calling agent (mTLS required) | capabilities/system.mesh.heartbeat |
| POST   | /v1/mesh/invoke-did/{target_did} | Resolve a target DID via the Capability Registry and forward the invocation to the owning product (v0.3 P6.3) | capabilities/system.mesh.invoke_did |
| POST   | /v1/mesh/invoke/{hostname} | Proxy an A2A call through the mesh (mTLS required) | capabilities/system.mesh.invoke |
| POST   | /v1/mesh/policies | Create a mesh allow/deny policy | capabilities/system.mesh.policies.create |
| GET    | /v1/mesh/policies | List mesh RBAC policies | capabilities/system.mesh.policies.list |
| DELETE | /v1/mesh/policies/{id} | Delete a mesh policy by id | capabilities/system.mesh.policies.delete |
| POST   | /v1/mesh/profiles | Create a mesh behavioral profile | capabilities/system.mesh.profiles.create |
| GET    | /v1/mesh/profiles | List mesh behavioral profiles | capabilities/system.mesh.profiles.list |
| DELETE | /v1/mesh/profiles/{role} | Delete a mesh behavioral profile by role | capabilities/system.mesh.profiles.delete |
| POST   | /v1/mesh/register | Register an agent in the service mesh (mTLS required) | capabilities/system.mesh.register |
| GET    | /v1/mesh/resolve/{hostname} | Resolve a mesh hostname to its agent registration | capabilities/system.mesh.resolve |

### OAuth
Auth: Supabase JWT or API Key

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /v1/oauth/apps | Register an OAuth app (developer-facing) | capabilities/system.oauth.apps.create |
| GET    | /v1/oauth/apps | List OAuth apps for the tenant | capabilities/system.oauth.apps.list |
| DELETE | /v1/oauth/apps/{id} | Revoke an OAuth app (soft delete — sets active=false) | capabilities/system.oauth.apps.delete |

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

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | /auth/admin/digest | Platform-admin daily digest (platform admin only) | capabilities/auth.admin.digest |
| POST   | /auth/admin/invite-codes | Create an invite code (platform admin only) | capabilities/auth.admin.invite_codes.create |
| GET    | /auth/admin/invite-codes | List invite codes (platform admin only) | capabilities/auth.admin.invite_codes.list |
| DELETE | /auth/admin/invite-codes/{id} | Delete an invite code (platform admin only) | capabilities/auth.admin.invite_codes.delete |
| GET    | /auth/admin/is-admin | Check whether the caller is on the platform-admin allowlist | capabilities/auth.admin.is_admin |
| GET    | /auth/admin/tenants | List tenants (platform admin only) | capabilities/auth.admin.tenants.list |
| GET    | /auth/admin/tenants/{id} | Get one tenant by ID (platform admin only) | capabilities/auth.admin.tenants.get |
| POST   | /auth/admin/tenants/{id}/approve | Approve a pending tenant (platform admin only) | capabilities/auth.admin.tenants.approve |
| PUT    | /auth/admin/tenants/{id}/rate-limit | Set per-tenant aggregate rate limit (platform admin only) | capabilities/auth.admin.tenants.set_rate_limit |
| POST   | /auth/admin/tenants/{id}/reject | Reject a pending tenant (platform admin only) | capabilities/auth.admin.tenants.reject |
| POST   | /auth/admin/tenants/{id}/suspend | Suspend an active tenant (platform admin only) | capabilities/auth.admin.tenants.suspend |
| POST   | /auth/agent-bootstrap | Onboard a new agent from the dashboard (admin/operator/developer) | capabilities/auth.agent_bootstrap |
| GET    | /auth/agent-manifests | List declared agent manifests for the tenant | capabilities/auth.agent_manifests.list |
| DELETE | /auth/agent-manifests/{agentId} | Delete an agent manifest declaration (admin only) | capabilities/auth.agent_manifests.delete |
| PUT    | /auth/agent-manifests/{agentId} | Create or update an agent manifest declaration (admin only) | capabilities/auth.agent_manifests.upsert |
| POST   | /auth/agent-profiles | Create a new agent profile (admin only) | capabilities/auth.agent_profiles.create |
| GET    | /auth/agent-profiles | List agent profiles for the tenant | capabilities/auth.agent_profiles.list |
| GET    | /auth/agent-profiles/{agentId} | Get a single agent profile by ID | capabilities/auth.agent_profiles.get |
| PATCH  | /auth/agent-profiles/{agentId} | Patch an agent profile, deep-merging hr_record metadata (admin only) | capabilities/auth.agent_profiles.update |
| POST   | /auth/agent-profiles/{agentId}/delegate | Delegate a sub-agent under a parent agent (admin only) | capabilities/auth.agent_profiles.delegate |
| GET    | /auth/agent-profiles/{agentId}/delegation-graph | Build the delegation graph rooted at an agent | capabilities/auth.agent_profiles.delegation_graph |
| GET    | /auth/agent-profiles/{agentId}/versions | Get version history for an agent profile | capabilities/auth.agent_profiles.versions |
| PATCH  | /auth/agent-profiles/lifecycle/{agentId} | Transition an agent profile to a new lifecycle state (admin only) | capabilities/auth.agent_profiles.lifecycle |
| DELETE | /auth/agent/sub-agents/{childAgentId} | Terminate a delegated sub-agent (admin only) | capabilities/auth.agent.sub_agents.terminate |
| GET    | /auth/analytics/latency-distribution | Latency-distribution histogram + percentiles | capabilities/auth.analytics.latency_distribution |
| GET    | /auth/analytics/timeseries | Usage time series (bucket = hour/day/week) | capabilities/auth.analytics.timeseries |
| GET    | /auth/anomaly/events | Anomaly-detection events for the tenant (last 100) | capabilities/auth.anomaly.events |
| GET    | /auth/anomaly/kill-switch | Kill-switch triggered events for the tenant (last 100) | capabilities/auth.anomaly.kill_switch |
| POST   | /auth/api-keys | Create a new dashboard-issued API key with optional controls | capabilities/auth.api_keys.create |
| GET    | /auth/api-keys | List the caller's API keys (masked, with controls) | capabilities/auth.api_keys.list |
| DELETE | /auth/api-keys/{id} | Revoke a dashboard-issued API key | capabilities/auth.api_keys.delete |
| POST   | /auth/approvals/{id}/approve | Approve a pending approval record | capabilities/auth.approvals.approve |
| POST   | /auth/approvals/{id}/reject | Reject a pending approval record | capabilities/auth.approvals.reject |
| GET    | /auth/approvals/pending | List pending approval records (auto-expires past expiresAt) | capabilities/auth.approvals.pending |
| GET    | /auth/billing/export | Export the last 30 days of usage events as CSV | capabilities/auth.billing.export |
| GET    | /auth/billing/summary | 30-day cost breakdown by provider, model, and API key | capabilities/auth.billing.summary |
| GET    | /auth/budget/agents | Agent budget configs + leaderboard | capabilities/auth.budget.agents.list |
| PUT    | /auth/budget/agents/{agentId} | Configure a per-agent budget | capabilities/auth.budget.agents.put |
| GET    | /auth/budget/alerts/config | Budget alert thresholds + webhook config | capabilities/auth.budget.alerts.config.get |
| PUT    | /auth/budget/alerts/config | Update budget alert configuration | capabilities/auth.budget.alerts.config.put |
| GET    | /auth/budget/alerts/history | Recent budget alert events | capabilities/auth.budget.alerts.history |
| GET    | /auth/budget/forecast | Budget forecast + anomaly detection from the last 30 days of spend | capabilities/auth.budget.forecast |
| GET    | /auth/budget/limits | Tenant budget limits (daily + monthly) | capabilities/auth.budget.limits.get |
| PUT    | /auth/budget/limits | Update tenant budget limits (merge: null clears, undefined leaves) | capabilities/auth.budget.limits.put |
| GET    | /auth/budget/status | Tenant-level budget status (daily + monthly spent vs. limits) | capabilities/auth.budget.status |
| POST   | /auth/certs/block-tenant | Suspend a tenant by revoking all live agent certs | capabilities/auth.certs.block_tenant |
| GET    | /auth/certs/revocations | List active cert revocations for the tenant | capabilities/auth.certs.revocations |
| POST   | /auth/certs/unblock-tenant | Reinstate a previously blocked tenant | capabilities/auth.certs.unblock_tenant |
| POST   | /auth/claim | Link OAuth identity to a machine-registered tenant by consuming a claim token | capabilities/auth.claim |
| POST   | /auth/connectors | Create a connector (credential encrypted via KMS envelope when present) | capabilities/auth.connectors.create |
| GET    | /auth/connectors | List active connectors (credentials redacted) | capabilities/auth.connectors.list |
| POST   | /auth/demo/seed | Seed synthetic firewall + anomaly + forensic + mesh events (admin role) | capabilities/auth.demo.seed |
| POST   | /auth/device/confirm | Confirm an OAuth device-code grant (browser-side, JWT-authenticated) | capabilities/auth.device.confirm |
| GET    | /auth/events | SSE stream — real-time dashboard updates (dual auth) | capabilities/auth.events.stream |
| POST   | /auth/explain | Dashboard GenAI explain bridge — route a freeform explain prompt | capabilities/auth.explain |
| GET    | /auth/firewall/interceptions | Tool firewall interception feed | capabilities/auth.firewall.interceptions |
| POST   | /auth/forensics/export | Signed forensic-export bundle (usage + security events, filtered) | capabilities/auth.forensics.export |
| GET    | /auth/forensics/session/{sessionId}/timeline | Stitched usage + security event timeline for a session | capabilities/auth.forensics.session.timeline |
| GET    | /auth/governance/audit/chain/verify | Verify the hash-chain integrity of the tenant's recent audit window | capabilities/auth.governance.audit.chainVerify |
| GET    | /auth/governance/audit/ledger | Recent chained audit rows projected for the Ledger view (+ head hash) | capabilities/auth.governance.audit.ledger |
| POST   | /auth/governance/audit/sign | Sign an audit entry with the tenant signing key (HMAC-SHA256) | capabilities/auth.governance.audit.sign |
| POST   | /auth/governance/audit/verify | Verify an audit entry's HMAC signature | capabilities/auth.governance.audit.verify |
| GET    | /auth/governance/behavioral-profiles | List behavioral profiles for the tenant | capabilities/auth.governance.behavioral_profiles.list |
| DELETE | /auth/governance/behavioral-profiles/{role} | Delete a behavioral profile by role (admin) | capabilities/auth.governance.behavioral_profiles.delete |
| PUT    | /auth/governance/behavioral-profiles/{role} | Create or update a behavioral profile for a role (admin) | capabilities/auth.governance.behavioral_profiles.update |
| GET    | /auth/governance/compliance | PII scan over the tenant's core memory entries | capabilities/auth.governance.compliance |
| GET    | /auth/governance/plans | List the tenant's request-scoped liaison plans (read-only; distinct from grants) | capabilities/auth.governance.plans |
| POST   | /auth/governance/policy/dry-run | Dry-run the tenant policy engine against a hypothetical action | capabilities/auth.governance.policy.dry_run |
| POST   | /auth/governance/scope-check | Dry multi-source scope composition (per-source lanes, no enforcement side effects) | capabilities/auth.governance.scope_check |
| GET    | /auth/governance/scope-enforcement | Per-source scope enforcement: configured vs effective (cohort-aware, R6) | capabilities/auth.governance.scope_enforcement |
| GET    | /auth/governance/would-deny | Would-deny preview: warn-mode denials over an adjustable lookback, deduped | capabilities/auth.governance.would_deny |
| GET    | /auth/grants | List grants for the tenant (filter by subject / status / root / capability) | capabilities/auth.grants.list |
| GET    | /auth/grants/{id} | Fetch a grant record + verified chain summary | capabilities/auth.grants.get |
| GET    | /auth/grants/{id}/chain | Export the per-link-verifiable chain bundle (envelopes + signatures + JWKS ref) | capabilities/auth.grants.chain |
| POST   | /auth/grants/{id}/check | Signed PDP verdict for a principal + requested scope (the dashboard simulator) | capabilities/auth.grants.check |
| POST   | /auth/grants/{id}/revoke | Break-glass revoke (tenant owner/admin; cascade default true; audited as override) | capabilities/auth.grants.revoke |
| GET    | /auth/guardrails/catalog | Guardrail check registry — tenant-agnostic catalog | capabilities/auth.guardrails.catalog |
| GET    | /auth/guardrails/config | Get the caller tenant's guardrail config | capabilities/auth.guardrails.config.get |
| PUT    | /auth/guardrails/config | Update the caller tenant's guardrail config | capabilities/auth.guardrails.config.update |
| POST   | /auth/guardrails/feedback | Submit guardrail feedback (false-positive / true-positive) | capabilities/auth.guardrails.feedback |
| GET    | /auth/guardrails/metrics | Per-scanner guardrail run/pass/fail/error metrics + feedback summary | capabilities/auth.guardrails.metrics |
| POST   | /auth/guardrails/pipelines | Create a new V2 guardrail pipeline | capabilities/auth.guardrails.pipelines.create |
| GET    | /auth/guardrails/pipelines | List V2 guardrail pipelines for the tenant | capabilities/auth.guardrails.pipelines.list |
| DELETE | /auth/guardrails/pipelines/{id} | Delete a V2 guardrail pipeline | capabilities/auth.guardrails.pipelines.delete |
| PUT    | /auth/guardrails/pipelines/{id} | Update an existing V2 guardrail pipeline | capabilities/auth.guardrails.pipelines.update |
| POST   | /auth/guardrails/pipelines/{id}/test | Execute a pipeline against a sample text — returns the check verdicts | capabilities/auth.guardrails.pipelines.test |
| GET    | /auth/insights/forecast | Spend forecast for the tenant | capabilities/auth.insights.forecast |
| GET    | /auth/insights/optimize | Optimization suggestions for cost / latency | capabilities/auth.insights.optimize |
| GET    | /auth/insights/savings | Estimated savings vs. baseline model selection | capabilities/auth.insights.savings |
| GET    | /auth/insights/waste | Waste insights (over-provisioned requests, duplicate work) | capabilities/auth.insights.waste |
| POST   | /auth/killswitch/scope | Activate a scoped kill switch (admin only) | capabilities/auth.killswitch.scope.activate |
| DELETE | /auth/killswitch/scope/{type}/{id} | Deactivate a scoped kill switch (admin only) | capabilities/auth.killswitch.scope.deactivate |
| GET    | /auth/killswitch/scopes | List active scoped kill-switches (per-agent / per-tool / per-provider) | capabilities/auth.killswitch.scopes.list |
| GET    | /auth/killswitch/status | Tenant kill-switch state + activation history | capabilities/auth.killswitch.status |
| GET    | /auth/logs | Paginated request log listing (provider/model/status/search filters) | capabilities/auth.logs.list |
| GET    | /auth/logs/{requestId} | Single request log detail | capabilities/auth.logs.detail |
| GET    | /auth/logs/{requestId}/content | Replay request/response content (opt-in via tenant content-logging flag) | capabilities/auth.logs.content |
| GET    | /auth/logs/{requestId}/rewrite | Poll for an async prompt-rewrite suggestion for a flagged request | capabilities/auth.logs.rewrite |
| GET    | /auth/logs/{requestId}/trace | Decision trace (Thompson-sampling routing breakdown) for a request | capabilities/auth.logs.trace |
| GET    | /auth/mcp/approvals | List pending MCP tool-execution approvals | capabilities/auth.mcp.approvals.list |
| POST   | /auth/mcp/approvals/{id}/approve | Approve a pending MCP execution | capabilities/auth.mcp.approvals.approve |
| POST   | /auth/mcp/approvals/{id}/deny | Deny a pending MCP execution | capabilities/auth.mcp.approvals.deny |
| GET    | /auth/mcp/audit | Recent MCP tool-execution audit entries | capabilities/auth.mcp.audit |
| GET    | /auth/mcp/governance | MCP governance status | capabilities/auth.mcp.governance.status |
| PUT    | /auth/mcp/governance/policy | Update MCP governance policy for a specific tool | capabilities/auth.mcp.governance.policy |
| POST   | /auth/mcp/servers | Register a new MCP server | capabilities/auth.mcp.servers.create |
| GET    | /auth/mcp/servers | List enabled MCP servers for the tenant | capabilities/auth.mcp.servers.list |
| DELETE | /auth/mcp/servers/{id} | Remove an MCP server | capabilities/auth.mcp.servers.delete |
| GET    | /auth/mcp/servers/{id} | Get one MCP server (redacted) | capabilities/auth.mcp.servers.get |
| PUT    | /auth/mcp/servers/{id} | Update an MCP server | capabilities/auth.mcp.servers.update |
| POST   | /auth/mcp/servers/{id}/discover | Re-discover an MCP server's tools | capabilities/auth.mcp.server.discover |
| POST   | /auth/mcp/servers/{id}/health | Trigger an MCP server health probe | capabilities/auth.mcp.server.health.check |
| GET    | /auth/mcp/servers/{id}/health | Cached MCP server health status | capabilities/auth.mcp.server.health.status |
| GET    | /auth/mcp/tools | List all MCP tools discoverable across servers | capabilities/auth.mcp.tools.list |
| GET    | /auth/me | Resilient self-fetch — same as /provision but read-only-typed | capabilities/auth.me |
| GET    | /auth/memory/blocks | List per-block memory stats for the caller's tenant | capabilities/auth.memory.blocks |
| POST   | /auth/memory/entries | Create a core memory entry | capabilities/auth.memory.entries.create |
| GET    | /auth/memory/entries | List all core memory entries for the caller's tenant | capabilities/auth.memory.entries.list |
| DELETE | /auth/memory/entries/{id} | Delete a core memory entry | capabilities/auth.memory.entries.delete |
| PUT    | /auth/memory/entries/{id} | Update a core memory entry (fact text and/or pin status) | capabilities/auth.memory.entries.update |
| GET    | /auth/memory/pending | List pending memory-write approvals | capabilities/auth.memory.pending.list |
| POST   | /auth/memory/pending/{id}/approve | Approve a pending memory write (commits to shared memory) | capabilities/auth.memory.pending.approve |
| POST   | /auth/memory/pending/{id}/reject | Reject a pending memory write | capabilities/auth.memory.pending.reject |
| POST   | /auth/memory/query | Score-rank core memory entries against a query string | capabilities/auth.memory.query |
| GET    | /auth/memory/shared/entries | List shared-memory entries (tenant-wide) | capabilities/auth.memory.shared.list |
| POST   | /auth/memory/shared/store | Store a shared-memory entry (may enqueue for approval) | capabilities/auth.memory.shared.store |
| GET    | /auth/mesh/agents | List mesh agents currently registered for the tenant | capabilities/auth.mesh.agents |
| GET    | /auth/mesh/forensics | List forensic snapshots for the tenant (normalized for dashboard) | capabilities/auth.mesh.forensics.list |
| GET    | /auth/mesh/forensics/{id} | Get a single forensic snapshot by ID | capabilities/auth.mesh.forensics.get |
| GET    | /auth/mesh/graph | Live mesh-graph snapshot (nodes + aggregated edges) | capabilities/auth.mesh.graph |
| GET    | /auth/mesh/graph/history | Mesh-graph snapshot history (rolling 1–168h window) | capabilities/auth.mesh.graph_history |
| GET    | /auth/models | Available model list for the dashboard (no auth) | capabilities/auth.models.list |
| GET    | /auth/models/catalog | Full pricing catalog across all providers (no auth) | capabilities/auth.models.catalog |
| GET    | /auth/models/leaderboard | Model performance rankings (Thompson-sampling reward + live metrics) | capabilities/auth.models.leaderboard |
| POST   | /auth/oauth/authorize | OAuth 2.0 PKCE authorize POST — user approves, server issues code | capabilities/oauth.authorize.approve |
| GET    | /auth/oauth/authorize | OAuth 2.0 PKCE authorize endpoint — returns app info for consent UI | capabilities/oauth.authorize.consent |
| POST   | /auth/oauth/token | OAuth 2.0 PKCE token exchange — code + verifier → scoped API key | capabilities/oauth.token.exchange |
| GET    | /auth/observability/config | Get the tenant broadcast config (destinations + enabled flag) | capabilities/auth.observability.config.get |
| POST   | /auth/observability/destinations | Create an observability destination (broadcast sink) | capabilities/auth.observability.destinations.create |
| DELETE | /auth/observability/destinations/{id} | Delete an observability destination | capabilities/auth.observability.destinations.delete |
| PUT    | /auth/observability/destinations/{id} | Update an observability destination | capabilities/auth.observability.destinations.update |
| GET    | /auth/onboarding/metrics | Time-to-first-completion metrics for the onboarding wizard | capabilities/auth.onboarding.metrics |
| GET    | /auth/onboarding/status | Get onboarding wizard state for the tenant | capabilities/auth.onboarding.get |
| PUT    | /auth/onboarding/status | Update onboarding wizard state (merge with current) | capabilities/auth.onboarding.put |
| GET    | /auth/ops/cache | Semantic + exact-match cache stats; persistent hit-rate from usage_events | capabilities/auth.ops.cache |
| GET    | /auth/ops/guardian-stats | Guardian overhead, cache hit rate, anomaly count — dashboard JWT | capabilities/auth.ops.guardian_stats |
| GET    | /auth/ops/status | Endpoint health + budget + usage summary (live router fallback to DB) | capabilities/auth.ops.status |
| POST   | /auth/playground/completions | Dashboard playground completions proxy (Supabase JWT) | capabilities/auth.playground.completions |
| POST   | /auth/projects | Create a project under a workspace | capabilities/auth.projects.create |
| GET    | /auth/projects | List active projects (optionally filtered by workspaceId) | capabilities/auth.projects.list |
| POST   | /auth/prompts | Create a new prompt template (version 1) | capabilities/auth.prompts.create |
| GET    | /auth/prompts | List prompt templates (non-archived) | capabilities/auth.prompts.list |
| DELETE | /auth/prompts/{id} | Archive a prompt (soft-delete: marks archived flag) | capabilities/auth.prompts.delete |
| GET    | /auth/prompts/{id} | Get one prompt template (with all versions) | capabilities/auth.prompts.get |
| PUT    | /auth/prompts/{id} | Update a prompt — appends a new version, doesn't mutate existing | capabilities/auth.prompts.update |
| POST   | /auth/prompts/{id}/ab | Start or stop an A/B test on a prompt | capabilities/auth.prompts.ab.action |
| GET    | /auth/prompts/{id}/ab | Get current A/B test state for a prompt | capabilities/auth.prompts.ab.get |
| GET    | /auth/prompts/{id}/diff | Unified diff between two versions of a prompt template | capabilities/auth.prompts.diff |
| POST   | /auth/prompts/{id}/promote | Promote a prompt version to a target environment | capabilities/auth.prompts.promote |
| POST   | /auth/prompts/{id}/test | Render a prompt template with the supplied variables (dry-run) | capabilities/auth.prompts.test |
| POST   | /auth/provider-keys | Store a new encrypted provider key (BYOK) | capabilities/auth.provider_keys.create |
| GET    | /auth/provider-keys | List active provider keys (masked, no plaintext) | capabilities/auth.provider_keys.list |
| DELETE | /auth/provider-keys/{id} | Deactivate a provider key (does not delete row) | capabilities/auth.provider_keys.delete |
| POST   | /auth/provision | Idempotent OAuth user provisioning — create or fetch the caller's tenant + user from a verified Supabase JWT | capabilities/auth.provision |
| GET    | /auth/routing/bandit | Thompson sampling bandit arm stats (strategy + per-arm) | capabilities/auth.routing.bandit |
| GET    | /auth/routing/cascades | Cascade activations (model escalation on failure) — dashboard JWT | capabilities/auth.routing.cascades |
| GET    | /auth/routing/decisions | Recent routing decisions with decisionTrace metadata (dashboard JWT) | capabilities/auth.routing.decisions |
| PUT    | /auth/routing/strategy | Set tenant routing strategy (price / quality / balanced) | capabilities/auth.routing.strategy |
| GET    | /auth/security-events | Tenant security event feed | capabilities/auth.security_events.list |
| GET    | /auth/security-events/summary | Governance violation rollup (N-day window) | capabilities/auth.security_events.summary |
| POST   | /auth/tasks | Create a task | capabilities/auth.tasks.create |
| GET    | /auth/tasks | List the tenant's tasks (proxies /v1/tasks logic) | capabilities/auth.tasks.list |
| DELETE | /auth/tasks/{id} | Delete a task | capabilities/auth.tasks.delete |
| GET    | /auth/tenant-settings | Get the tenant settings blob | capabilities/auth.tenant_settings.get |
| PATCH  | /auth/tenant-settings | Merge tenant settings (contentLogging + features merged deep, rest shallow) | capabilities/auth.tenant_settings.patch |
| DELETE | /auth/tenant/kms | Clear the tenant's KMS config (existing keys still decrypt via row-level ARNs) | capabilities/auth.tenant.kms.delete |
| GET    | /auth/tenant/kms | Get the tenant's KMS configuration | capabilities/auth.tenant.kms.get |
| PUT    | /auth/tenant/kms | Set the tenant's KMS ARNs (kmsArn required) | capabilities/auth.tenant.kms.put |
| POST   | /auth/tenant/kms/validate | Round-trip a test plaintext through the supplied KMS config | capabilities/auth.tenant.kms.validate |
| POST   | /auth/usage/{requestId}/feedback | Submit quality feedback for a request (0–1 score + comment) | capabilities/auth.usage.feedback |
| GET    | /auth/usage/daily | Daily usage time series | capabilities/auth.usage.daily |
| GET    | /auth/usage/models | Per-model usage breakdown for the tenant | capabilities/auth.usage.models |
| GET    | /auth/usage/summary | Aggregate usage stats for the tenant | capabilities/auth.usage.summary |
| GET    | /auth/workspace/files | List workspace filenames for the caller's agent scope | capabilities/workspace.files.list |
| DELETE | /auth/workspace/files/{filename} | Delete a workspace file | capabilities/workspace.files.delete |
| GET    | /auth/workspace/files/{filename} | Read a workspace file | capabilities/workspace.files.read |
| PUT    | /auth/workspace/files/{filename} | Create or update a workspace file | capabilities/workspace.files.write |
| POST   | /auth/workspaces | Create a workspace | capabilities/auth.workspaces.create |
| GET    | /auth/workspaces | List active (non-archived) workspaces for the tenant | capabilities/auth.workspaces.list |

### SCIM Provisioning
Auth: SCIM Bearer Token

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| POST   | /scim/v2/Groups | Create or upsert a SCIM group | capabilities/scim.groups.create |
| GET    | /scim/v2/Groups | List SCIM groups (filter + pagination) | capabilities/scim.groups.list |
| DELETE | /scim/v2/Groups/{id} | Delete a SCIM group | capabilities/scim.groups.delete |
| GET    | /scim/v2/Groups/{id} | Get a SCIM group by ID | capabilities/scim.groups.get |
| PATCH  | /scim/v2/Groups/{id} | Patch a SCIM group (Operations array) | capabilities/scim.groups.patch |
| PUT    | /scim/v2/Groups/{id} | Replace a SCIM group (PUT) | capabilities/scim.groups.replace |
| GET    | /scim/v2/ResourceTypes | SCIM 2.0 ResourceTypes | capabilities/scim.resource_types |
| GET    | /scim/v2/Schemas | SCIM 2.0 supported schemas | capabilities/scim.schemas |
| GET    | /scim/v2/ServiceProviderConfig | SCIM 2.0 ServiceProviderConfig (RFC 7644 §4) | capabilities/scim.service_provider_config |
| POST   | /scim/v2/Users | Create or upsert a SCIM user | capabilities/scim.users.create |
| GET    | /scim/v2/Users | List SCIM users (filter + pagination) | capabilities/scim.users.list |
| DELETE | /scim/v2/Users/{id} | Soft-delete a SCIM user (sets active=false) | capabilities/scim.users.delete |
| GET    | /scim/v2/Users/{id} | Get a SCIM user by ID | capabilities/scim.users.get |
| PATCH  | /scim/v2/Users/{id} | Patch a SCIM user (Operations array) | capabilities/scim.users.patch |
| PUT    | /scim/v2/Users/{id} | Replace a SCIM user (PUT) | capabilities/scim.users.replace |

### Other
Auth: API Key (Bearer)

| Method | Path | Description | Source |
|--------|------|-------------|--------|
| GET    | / | Arrival manifest — one document a frontier model reads to understand what BR does and how to use it | capabilities/discovery.root_manifest |
| GET    | /.well-known/agent-card.json | A2A v1.0 agent card — capability discovery for A2A-aware peers and frontier models | capabilities/discovery.agent_card |
| GET    | /.well-known/agents.json |  | server.ts |
| GET    | /.well-known/ai-plugin.json |  | server.ts |
| GET    | /.well-known/brainstorm/grant-keys |  | server.ts |
| GET    | /.well-known/build.json |  | server.ts |
| GET    | /attestation | Build attestation bundle (commit, image digest, signer, Rekor URL, verify command) | capabilities/security.attestation |
| GET    | /llms-full.txt |  | server.ts |
| GET    | /metrics | Prometheus-compatible metrics endpoint (text exposition format) | capabilities/system.metrics |
| GET    | /v1/a2a/agents | List agents with active behavior certificates | capabilities/security.a2a.agents.list |
| POST   | /v1/a2a/certificates | Issue a behavior certificate to an agent (201) | capabilities/security.a2a.certificates.issue |
| GET    | /v1/a2a/certificates/{agentId} | Fetch an agent's behavior certificate (404 on missing) | capabilities/security.a2a.certificates.get |
| DELETE | /v1/a2a/certificates/{agentId} | Revoke an agent's behavior certificate (404 on missing) | capabilities/security.a2a.certificates.revoke |
| POST   | /v1/a2a/discover | Discover agents in the tenant with their behavior-certificate capabilities | capabilities/security.a2a.discover |
| POST   | /v1/a2a/send | Send a message between agents; verifies behavior certificate + send_message capability | capabilities/security.a2a.send |
| GET    | /v1/admin/agents/reputation | Admin view: all agent reputations for the tenant | capabilities/intelligence.reputation.admin_list |
| GET    | /v1/admin/digest | Business summary digest | capabilities/system.admin.digest |
| POST   | /v1/admin/invite-codes | Create an invite code | capabilities/system.admin.inviteCodes.create |
| GET    | /v1/admin/invite-codes | List invite codes with usage counts | capabilities/system.admin.inviteCodes.list |
| DELETE | /v1/admin/invite-codes/{id} | Revoke an invite code | capabilities/system.admin.inviteCodes.delete |
| GET    | /v1/admin/tenants | List tenants with optional status filter (platform admin only) | capabilities/system.admin.tenants.list |
| GET    | /v1/admin/tenants/{id} | Get tenant detail | capabilities/system.admin.tenants.get |
| POST   | /v1/admin/tenants/{id}/approve | Approve a tenant (sets status → active) | capabilities/system.admin.tenants.approve |
| PUT    | /v1/admin/tenants/{id}/rate-limit | Set per-tenant aggregate rate limit (API-key variant; admin auth via path middleware) | capabilities/system.admin.tenants.set_rate_limit |
| POST   | /v1/admin/tenants/{id}/reject | Reject a tenant (sets status → rejected) | capabilities/system.admin.tenants.reject |
| POST   | /v1/admin/tenants/{id}/suspend | Suspend a tenant (sets status → suspended) | capabilities/system.admin.tenants.suspend |
| DELETE | /v1/admin/xdr/risk-push | Clear an XDR risk score (risk resolved) | capabilities/system.admin.xdr.riskDelete |
| POST   | /v1/admin/xdr/risk-push | Push an XDR risk score for an agent (gated by XDR_BIDIRECTIONAL_ENABLED) | capabilities/system.admin.xdr.riskPush |
| POST   | /v1/approvals/{id}/approve | Approve a pending request and execute its deferred action | capabilities/system.approvals.approve |
| POST   | /v1/approvals/{id}/reject | Reject a pending request without executing its action | capabilities/system.approvals.reject |
| GET    | /v1/approvals/pending | List pending approval requests for the tenant | capabilities/system.approvals.pending |
| POST   | /v1/approvals/queue | Submit a deferred action for human review | capabilities/system.approvals.queue |
| POST   | /v1/audio/speech | OpenAI-compatible TTS (binary audio response) | capabilities/audio.speech |
| POST   | /v1/audio/transcriptions | OpenAI-compatible audio transcription (Whisper, multipart upload) | capabilities/audio.transcribe |
| GET    | /v1/audit/events | Search audit events (filterable by actor/action/resource/date range) | capabilities/security.audit.events |
| GET    | /v1/audit/export | Export audit events as CSV / JSON / CEF (raw Response with content-type) | capabilities/security.audit.export |
| GET    | /v1/audit/retention | Get current audit retention policy (days) | capabilities/security.audit.retention.get |
| PUT    | /v1/audit/retention | Set audit retention policy (allowed: 7, 30, 90, 365, 1095, 2555 days) | capabilities/security.audit.retention.set |
| GET    | /v1/audit/verify | Verify hash-chain integrity for the current tenant's audit trail | capabilities/security.audit.verify |
| POST   | /v1/auth/device/authorize | Start a device-authorization flow (admin scope required) | capabilities/system.identity.device_authorize |
| POST   | /v1/auth/device/token | Poll device-authorization status | capabilities/system.identity.device_token |
| POST   | /v1/auth/link | Generate a browser-based dashboard link URL (admin scope) | capabilities/system.identity.link |
| GET    | /v1/billing/plan | Current tenant plan + usage vs limits | capabilities/system.billing.plan.get |
| PUT    | /v1/billing/plan | Switch the tenant's billing plan (admin-only) | capabilities/system.billing.plan.update |
| GET    | /v1/billing/plans | List available billing plans | capabilities/system.billing.plans.list |
| POST   | /v1/bridge/messages | Anthropic Messages API with automatic MCP tool execution — explicit opt-in endpoint | capabilities/system.messages.bridge |
| GET    | /v1/budget/agents | List per-agent budget configurations and current status | capabilities/system.budget.listAgents |
| PUT    | /v1/budget/agents/{agentId} | Set budget configuration for a specific agent | capabilities/system.budget.setAgent |
| GET    | /v1/budget/alerts/config | Get current budget alert configuration | capabilities/system.budget.alertsConfigGet |
| PUT    | /v1/budget/alerts/config | Update budget alert configuration (thresholds, webhook, enabled) | capabilities/system.budget.alertsConfigSet |
| GET    | /v1/budget/alerts/history | Recent budget alert events for the tenant | capabilities/system.budget.alertsHistory |
| GET    | /v1/budget/forecast | Spend forecast, projected depletion date, anomaly detection | capabilities/system.budget.forecast |
| PUT    | /v1/budget/limits | Update tenant-level daily and monthly budget limits | capabilities/system.budget.setLimits |
| GET    | /v1/budget/status | Current tenant + key spend against daily/monthly limits | capabilities/system.budget.status |
| GET    | /v1/capabilities/{capability_id}/describe | Behavior block for one capability — effects, cost shape, security profile, composition, recovery vocabulary | capabilities/discovery.capability.describe |
| POST   | /v1/compare | Fan a prompt out to 2–6 models in parallel and compare cost/latency/quality | capabilities/intelligence.compare |
| POST   | /v1/connectors | Register an external connector with KMS-encrypted credentials | capabilities/system.connectors.create |
| GET    | /v1/connectors | List active external connectors | capabilities/system.connectors.list |
| DELETE | /v1/connectors/{id} | Soft-delete a connector (status=disabled, kept for audit) | capabilities/system.connectors.delete |
| GET    | /v1/connectors/{id} | Get a connector by id (credential envelope NEVER returned) | capabilities/system.connectors.get |
| PUT    | /v1/connectors/{id} | Update a connector (re-encrypts credential if supplied) | capabilities/system.connectors.update |
| POST   | /v1/connectors/{id}/test | Probe connector connectivity (HEAD baseUrl with decrypted auth) | capabilities/system.connectors.test |
| POST   | /v1/consensus | Evaluate multi-model consensus (majority/quality/weighted) with optional fan-out | capabilities/intelligence.consensus |
| GET    | /v1/discovery | Self-describing capability discovery — routing, models, budget, headers, errors | capabilities/system.discovery |
| POST   | /v1/estimate | Predict per-model cost for a completion request (no provider calls) | capabilities/intelligence.estimate |
| POST   | /v1/eval/datasets | Create an evaluation dataset | capabilities/system.eval.datasets.create |
| GET    | /v1/eval/datasets | List evaluation datasets for the tenant | capabilities/system.eval.datasets.list |
| DELETE | /v1/eval/datasets/{id} | Delete an evaluation dataset and all its items | capabilities/system.eval.datasets.delete |
| GET    | /v1/eval/datasets/{id} | Get an evaluation dataset | capabilities/system.eval.datasets.get |
| PUT    | /v1/eval/datasets/{id} | Update an evaluation dataset (name, description) | capabilities/system.eval.datasets.update |
| GET    | /v1/eval/datasets/{id}/export | Export dataset items (JSON default, CSV via ?format=csv) | capabilities/system.eval.datasets.export |
| POST   | /v1/eval/datasets/{id}/import-from-logs | Import items from production completion audit logs | capabilities/system.eval.datasets.import_logs |
| POST   | /v1/eval/datasets/{id}/items | Append items to an evaluation dataset (batch) | capabilities/system.eval.datasets.add_items |
| GET    | /v1/eval/datasets/{id}/items | List items in an evaluation dataset | capabilities/system.eval.datasets.list_items |
| DELETE | /v1/eval/datasets/{id}/items/{itemId} | Delete a single dataset item | capabilities/system.eval.datasets.delete_item |
| POST   | /v1/experiments | Create an A/B-test experiment with weighted variants | capabilities/intelligence.experiments.create |
| GET    | /v1/experiments | List experiments for the tenant | capabilities/intelligence.experiments.list |
| GET    | /v1/experiments/{id} | Get an experiment with interim results + statistical significance | capabilities/intelligence.experiments.get |
| POST   | /v1/experiments/{id}/outcomes | Record an outcome for an experiment variant | capabilities/intelligence.experiments.record_outcome |
| GET    | /v1/explain/{request_id} | Per-request routing-decision trace; optional LLM-narrated postmortem | capabilities/intelligence.explain_request |
| POST   | /v1/feedback/{requestId} | Report outcome (success/partial/failure) for a routed request; reward feeds Thompson sampling | capabilities/intelligence.feedback |
| GET    | /v1/firewall/interceptions | List firewall interceptions (tool_firewall violations or guardrail warnings) | capabilities/security.firewall.interceptions |
| GET    | /v1/fleet/insights | Fleet model insights — top 10 by evaluations or model-specific | capabilities/intelligence.fleet_insights |
| POST   | /v1/forensics/export | HMAC-signed forensic export bundle (usage + security events) | capabilities/system.forensics.export |
| GET    | /v1/forensics/session/{sessionId}/timeline | Reconstruct chronological timeline of events for a session | capabilities/system.forensics.timeline |
| POST   | /v1/god-mode/execute | Execute a Platform Contract tool by name (ChangeSet for mutations) | capabilities/system.godMode.execute |
| GET    | /v1/god-mode/tools | Discover Brainstorm Platform Contract tools available on BR | capabilities/system.godMode.tools |
| POST   | /v1/grants | Mint a root capability grant (api_key auth; root scope ⊆ issuer effective scope) | capabilities/grants.issue |
| GET    | /v1/grants | List grants for the tenant (filter by subject / status / root) | capabilities/grants.list |
| GET    | /v1/grants/{id} | Fetch a grant record + verified chain summary | capabilities/grants.get |
| POST   | /v1/grants/{id}/attenuate | Derive a child grant (identity == parent subject; double subset bound) | capabilities/grants.attenuate |
| GET    | /v1/grants/{id}/chain | Export the per-link-verifiable chain bundle (envelopes + signatures + JWKS ref) | capabilities/grants.chain |
| POST   | /v1/grants/{id}/check | Standalone PDP: signed allow/deny verdict for a principal + requested scope | capabilities/grants.check |
| POST   | /v1/grants/{id}/revoke | Revoke a grant (issuer / ancestor-subject; admin role: any; cascade default true) | capabilities/grants.revoke |
| GET    | /v1/health/providers | Per-provider health combining sentinel probes, circuit breakers, and BYOK key presence | capabilities/system.health.providers |
| POST   | /v1/images/generations | OpenAI-compatible image generation (proxied to provider) | capabilities/images.generate |
| POST   | /v1/intelligence/advise | Predictive routing recommendation with reasoning, evidence, and alternatives | capabilities/intelligence.advise |
| GET    | /v1/intelligence/benchmark | Thompson-vs-static shadow comparator results + statistical significance | capabilities/intelligence.benchmark |
| GET    | /v1/intelligence/compare | Head-to-head comparison of 2-10 models | capabilities/intelligence.compare_models |
| GET    | /v1/intelligence/degradation | Current degradation ladder state: level, reason, thresholds, budget utilization | capabilities/intelligence.degradation |
| GET    | /v1/intelligence/deprecations | Active deprecation alerts (filter by provider, level) | capabilities/intelligence.deprecations |
| GET    | /v1/intelligence/frontier | Cost-quality Pareto frontier with dominated models | capabilities/intelligence.frontier |
| GET    | /v1/intelligence/institutional | Institutional intelligence (I3) index for the tenant | capabilities/system.intelligence.institutional |
| GET    | /v1/intelligence/model/{provider}/{modelId} | Single model profile with ranking + deprecation alert | capabilities/intelligence.model_profile |
| GET    | /v1/intelligence/patterns | Aggregated request-pattern × model performance data with optional filters | capabilities/intelligence.patterns.list |
| GET    | /v1/intelligence/rankings | Overall (or task-specific) model leaderboard | capabilities/intelligence.rankings |
| GET    | /v1/intelligence/sampling-audit | Routing-sampling audit (agent trap defense) | capabilities/system.intelligence.samplingAudit |
| GET    | /v1/intelligence/savings | Counterfactual ROI savings (Postgres-backed when configured) | capabilities/intelligence.savings |
| GET    | /v1/intelligence/status | Ingestor diagnostics, store size, deprecation alert count | capabilities/intelligence.status |
| POST   | /v1/killswitch/activate | Emergency stop — suspend all routing for the authenticated tenant | capabilities/security.killswitch.activate |
| POST   | /v1/killswitch/deactivate | Resume routing for the authenticated tenant | capabilities/security.killswitch.deactivate |
| POST   | /v1/killswitch/scope | Activate a scoped kill switch (agent, tool, or provider) | capabilities/security.killswitch.scope_set |
| DELETE | /v1/killswitch/scope/{type}/{id} | Deactivate a scoped kill switch | capabilities/security.killswitch.scope_delete |
| GET    | /v1/killswitch/scopes | List all active scoped kill switches for the tenant | capabilities/security.killswitch.scopes_list |
| GET    | /v1/killswitch/status | Get current kill switch state + activation history | capabilities/security.killswitch.status |
| POST   | /v1/liaison/{liaison_id}/close | Finalize a liaison — emit cost summary, trace digest, expire delegations | capabilities/liaison.close |
| GET    | /v1/liaison/{liaison_id}/events | SSE stream of routing decisions and trace envelopes scoped to a liaison session | capabilities/liaison.events |
| POST   | /v1/liaison/{liaison_id}/plan | Mint a signed pre-flight contract binding cost ceiling + prompt fingerprint | capabilities/liaison.plan |
| POST   | /v1/liaison/open | Open a negotiation session — mint signed liaison_id and SSE downlink URL | capabilities/liaison.open |
| POST   | /v1/messages | Anthropic-compatible messages endpoint — translates body to OpenAI format, runs the shared completions pipeline, translates the response back to Anthropic format | capabilities/completions.messages.create |
| GET    | /v1/messages | Token-validation endpoint for Anthropic-compatible clients (Claude for Excel/PowerPoint add-ins) | capabilities/completions.messages.health |
| POST   | /v1/moderations | OpenAI-compatible moderation endpoint with BR jailbreak/PII layer | capabilities/security.moderations |
| POST   | /v1/onboard | Personalized one-call agent setup: identity, models, tools, budget, bootstrap path | capabilities/system.onboard |
| GET    | /v1/operator-registry/list | List operator-facing god-mode capabilities from the platform operator-capability registry (v0.5 M00a SoR). Used by the HAI chat dispatcher + capability browser. | capabilities/system.operator_registry.list |
| POST   | /v1/patterns | Store a learned task pattern (tenant-scoped) | capabilities/intelligence.patterns.store |
| GET    | /v1/patterns/recommend | Aggregated task-pattern recommendations across all tenants | capabilities/intelligence.patterns.recommend |
| POST   | /v1/projects | Create a project under an existing workspace | capabilities/system.projects.create |
| GET    | /v1/projects | List active projects (optionally filtered by ?workspaceId=) | capabilities/system.projects.list |
| DELETE | /v1/projects/{id} | Archive a project (soft-delete) | capabilities/system.projects.archive |
| GET    | /v1/projects/{id} | Get a project by id | capabilities/system.projects.get |
| PUT    | /v1/projects/{id} | Update a project (partial) | capabilities/system.projects.update |
| GET    | /v1/projects/{id}/activity | Get recent activity for a project (filterable by ?since=1h) | capabilities/system.projects.activity_get |
| POST   | /v1/projects/{id}/activity | Report an activity record for a project | capabilities/system.projects.activity_post |
| GET    | /v1/projects/{id}/config | Get a project's routing config | capabilities/system.projects.config_get |
| POST   | /v1/projects/{id}/config | Set project routing config (default model, budget, conventions, etc.) | capabilities/system.projects.config_set |
| GET    | /v1/projects/registry | List registered projects for the current tenant | capabilities/system.projects.registry.list |
| POST   | /v1/projects/registry | Register or sync a project (upsert by name; 201 on create, 200 on update) | capabilities/system.projects.registry.upsert |
| GET    | /v1/projects/registry/{name} | Get a single registered project by name (404 on missing) | capabilities/system.projects.registry.get |
| PUT    | /v1/projects/registry/{name} | Update project metadata (404 on missing) | capabilities/system.projects.registry.update |
| GET    | /v1/rbac/my-permissions | Caller's RBAC posture — roles, granted/denied permissions, upgrade paths | capabilities/system.rbac.my_permissions |
| POST   | /v1/recommend | Ranked model recommendations backed by production routing data | capabilities/intelligence.recommend |
| POST   | /v1/register | Machine registration — create tenant + admin user + API key atomically | capabilities/system.register |
| POST   | /v1/route | Brainstorm CLI delegated routing — pick a model for a task spec | capabilities/intelligence.routing.delegated |
| GET    | /v1/routing-stream | SSE stream of live routing decisions for the tenant | capabilities/intelligence.routing.stream |
| DELETE | /v1/routing/canary | Remove canary configuration | capabilities/intelligence.canary.delete |
| GET    | /v1/routing/canary | Read current canary configuration | capabilities/intelligence.canary.get |
| POST   | /v1/routing/canary | Set the canary traffic-split configuration for the current tenant | capabilities/intelligence.canary.set |
| GET    | /v1/routing/canary/results | Per-variant outcome statistics for the active canary | capabilities/intelligence.canary.results |
| GET    | /v1/routing/cascades | Cascade activations (model escalation on failure) | capabilities/intelligence.routing.cascades |
| GET    | /v1/routing/decisions | Recent routing decisions with decisionTrace metadata | capabilities/intelligence.routing.decisions |
| GET    | /v1/runs/active | All active runs for the tenant (status = running) | capabilities/system.agents.runs.active |
| GET    | /v1/security/anomalies | Recent per-tenant anomaly alerts (process-local) | capabilities/security.anomalies.alerts |
| GET    | /v1/security/anomalies/baselines | Export the tenant's anomaly-detection baselines | capabilities/security.anomalies.baselines_get |
| POST   | /v1/security/anomalies/baselines | Import previously-exported anomaly-detection baselines | capabilities/security.anomalies.baselines_set |
| GET    | /v1/security/anomalies/stats/{entityType}/{entityId}/{metric} | Per-entity per-metric anomaly stats | capabilities/security.anomalies.stats |
| GET    | /v1/security/owasp-coverage | OWASP LLM Top 10 coverage assessment for the current tenant's controls | capabilities/security.owasp.coverage |
| GET    | /v1/security/owasp-items | OWASP LLM Top 10 item catalog (id, title, description, controls) | capabilities/security.owasp.items |
| GET    | /v1/security/policies | Read the tenant's policy ruleset | capabilities/security.policies.get |
| PUT    | /v1/security/policies | Update the tenant's policy ruleset (invalidates policy-engine cache) | capabilities/security.policies.set |
| GET    | /v1/security/policies/presets | Built-in policy presets (e.g. L3 baseline) | capabilities/security.policies.presets |
| POST   | /v1/security/policies/test | Evaluate a context against the tenant's policy ruleset | capabilities/security.policies.test |
| POST   | /v1/security/red-team | Start an automated red-team run against a model | capabilities/security.red_team.create |
| GET    | /v1/security/red-team | List red-team runs for the current tenant | capabilities/security.red_team.list |
| GET    | /v1/security/red-team/{id} | Fetch a red-team run by ID | capabilities/security.red_team.get |
| GET    | /v1/security/red-team/categories | Supported red-team categories | capabilities/security.red_team.categories |
| GET    | /v1/security/shadow-ai/alerts | List shadow-AI alerts for the current tenant (filterable by type/severity) | capabilities/security.shadow_ai.alerts |
| POST   | /v1/security/shadow-ai/alerts/{id}/ack | Acknowledge a shadow-AI alert by ID | capabilities/security.shadow_ai.ack_alert |
| POST   | /v1/security/shadow-ai/reset-baseline | Reset the detection baseline for the current tenant | capabilities/security.shadow_ai.reset_baseline |
| GET    | /v1/security/shadow-ai/scan-config | Get the scan configuration for the current tenant | capabilities/security.shadow_ai.scan_config.get |
| POST   | /v1/security/shadow-ai/scan-config | Update the scan configuration (merges with existing config) | capabilities/security.shadow_ai.scan_config.set |
| POST   | /v1/security/shadow-ai/scan-now | Trigger an immediate scan and return the execution record | capabilities/security.shadow_ai.scan_now |
| GET    | /v1/security/shadow-ai/scans/{id} | Fetch a scan result by ID | capabilities/security.shadow_ai.scan.get |
| GET    | /v1/security/shadow-ai/summary | Alert summary counts for the current tenant | capabilities/security.shadow_ai.summary |
| GET    | /v1/security/siem | Get SIEM destination config (auth token never returned) | capabilities/security.siem.get |
| PUT    | /v1/security/siem | Set SIEM destination config (auth token KMS-encrypted) | capabilities/security.siem.set |
| GET    | /v1/security/status | Overall security posture — policy + anomaly tracking summary | capabilities/security.status |
| GET    | /v1/self | Agent self-awareness — identity, health, budget, memory, suggestions | capabilities/system.self |
| POST   | /v1/sessions/{id}/state | Save session state (≤1MB blob, upserts by session id) | capabilities/system.sessions.save |
| GET    | /v1/sessions/latest | Get the most recently updated session for a project | capabilities/system.sessions.latest |
| GET    | /v1/telemetry/live | SSE telemetry stream: model health, budget alerts, routing decisions | capabilities/system.telemetry.live |
| POST   | /v1/tenant/claim-link | Generate a dashboard claim link (admin scope required) | capabilities/system.identity.claim_link |
| GET    | /v1/tenant/context | Canonical tenant-context resolver: {workspace, products, entitlements, residency, members}. v0.4 P2 M24. | capabilities/system.tenant.context |
| POST   | /v1/workflows | Create a workflow definition (optionally cloned from a preset) | capabilities/system.workflows.create |
| GET    | /v1/workflows | List workflow definitions for the tenant | capabilities/system.workflows.list |
| DELETE | /v1/workflows/{id} | Delete a workflow definition | capabilities/system.workflows.delete |
| GET    | /v1/workflows/{id} | Get a workflow definition by id | capabilities/system.workflows.get |
| POST   | /v1/workflows/auto-select | Auto-select a workflow preset from a natural-language description | capabilities/system.workflows.autoSelect |
| GET    | /v1/workflows/presets | List available workflow presets | capabilities/system.workflows.presets.list |
| POST   | /v1/workflows/run | Run a workflow and stream events via SSE | capabilities/system.workflows.run |
| GET    | /v1/workflows/runs | List recent workflow runs for the tenant | capabilities/system.workflows.runs.list |
| GET    | /v1/workflows/runs/{id} | Get a workflow run by id | capabilities/system.workflows.runs.get |
| POST   | /v1/workflows/runs/{id}/cancel | Cancel a workflow run | capabilities/system.workflows.runs.cancel |
| POST   | /v1/workspaces | Create a workspace under the tenant | capabilities/system.workspaces.create |
| GET    | /v1/workspaces | List active workspaces for the tenant | capabilities/system.workspaces.list |
| DELETE | /v1/workspaces/{id} | Archive a workspace (soft-delete) | capabilities/system.workspaces.archive |
| GET    | /v1/workspaces/{id} | Get a workspace by id | capabilities/system.workspaces.get |
| PUT    | /v1/workspaces/{id} | Update workspace metadata (name, slug, settings, etc.) | capabilities/system.workspaces.update |
| POST   | /webhooks/slack/action |  | admin.ts |

---

## Examples

### Chat Completion
```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
  }'
```

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

### Query Memory
```bash
curl -X POST https://api.brainstormrouter.com/v1/memory/query \
  -H "Authorization: Bearer br_live_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 br_live_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 br_live_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: "br_live_..." });
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="br_live_...")
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: 654