Kill Switch

Emergency stop for tenant routing — activate, deactivate, and status.

Endpoints

Method	Path	Auth	Description
POST	/v1/killswitch/activate	API Key	Activate kill switch
POST	/v1/killswitch/deactivate	API Key	Deactivate kill switch
GET	/v1/killswitch/status	API Key	Get current state and history

Dashboard bridge endpoints (JWT auth):

Method	Path	Auth	Description
GET	/auth/killswitch/status	JWT	Kill switch state

Activate

Immediately suspends all non-exempt endpoints for the tenant. Blocked requests return 503 Service Unavailable with X-BR-Kill-Switch: active.

curl -X POST "https://api.brainstormrouter.com/v1/killswitch/activate" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "security incident #123"}'

Request body

Field	Type	Required	Description
reason	string	Yes	Human-readable activation reason

Response

{
  "ok": true,
  "active": true,
  "activated_at": "2026-03-10T15:00:00Z",
  "activated_by": "key_abc",
  "reason": "security incident #123"
}

Returns 409 Conflict if the kill switch is already active.

Deactivate

Resumes routing for the tenant. The activation is appended to history.

curl -X POST "https://api.brainstormrouter.com/v1/killswitch/deactivate" \
  -H "Authorization: Bearer br_live_..."

Response

{
  "ok": true,
  "active": false,
  "deactivated_at": "2026-03-10T16:00:00Z"
}

Returns 409 Conflict if the kill switch is not active.

Get status

Returns current kill switch state and activation history (last 50 events).

curl "https://api.brainstormrouter.com/v1/killswitch/status" \
  -H "Authorization: Bearer br_live_..."

Response

{
  "tenant_id": "t_001",
  "active": false,
  "activated_at": null,
  "activated_by": null,
  "reason": null,
  "history": [
    {
      "activatedAt": "2026-03-09T10:00:00Z",
      "deactivatedAt": "2026-03-09T11:00:00Z",
      "activatedBy": "key_abc",
      "reason": "test activation"
    }
  ]
}

Scoped kill switches

Scoped kill switches disable routing for a specific agent, tool, or provider without affecting the entire tenant. Useful for isolating a rogue agent or blocking a failing provider.

Activate scope

curl -X POST "https://api.brainstormrouter.com/v1/killswitch/scope" \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type": "agent", "id": "agent-007", "reason": "behavioral anomaly"}'

Field	Type	Required	Description
type	string	Yes	agent, tool, or provider
id	string	Yes	Identifier for the target
reason	string	No	Reason for activation

Response: { "ok": true, "type": "agent", "id": "agent-007", "reason": "behavioral anomaly" }

List active scopes

curl "https://api.brainstormrouter.com/v1/killswitch/scopes" \
  -H "Authorization: Bearer br_live_..."

Response:

{
  "scopes": [
    {
      "type": "agent",
      "id": "agent-007",
      "reason": "behavioral anomaly",
      "activatedBy": "key_abc",
      "activatedAt": "2026-03-10T15:00:00Z"
    }
  ],
  "count": 1
}

Deactivate scope

curl -X DELETE "https://api.brainstormrouter.com/v1/killswitch/scope/agent/agent-007" \
  -H "Authorization: Bearer br_live_..."

Response: { "ok": true, "type": "agent", "id": "agent-007" }

Returns 404 if scope not found or already deactivated.

Scope enforcement

When a scoped kill switch is active:

• Agent scope: Requests with X-BR-Agent-Id header matching the blocked agent return 503.
• Provider scope: Requests with a model name prefixed by the blocked provider (e.g., claude* → anthropic) return 503.
• Tool scope: POST requests with tool_choice or tools[] matching the blocked tool return 503.
• Scoped checks run after the tenant-level kill switch check. If both are active, tenant-level takes precedence.
• Fail-open: errors in scope checking are silently ignored (the request proceeds).

Enforcement behavior

• Scope: When active, the kill switch blocks all tenant-scoped /v1/* requests except those matching the exempt prefix list below. Any non-exempt path returns 503 Service Unavailable.
• Exempt paths (accessible during activation):
• /v1/budget/, /v1/killswitch/ — governance
• /v1/security/, /v1/governance/ — security & audit
• /v1/usage/, /v1/insights/, /v1/ops/* — observability
• /v1/mcp/connect — MCP transport (tool-level enforcement applies separately)
• /v1/models, /v1/api-keys, /v1/config — configuration
• /health — health check
• Blocked paths include: /v1/chat/completions, /v1/embeddings, /v1/tasks/, /v1/memory/, and any other non-exempt route.
• Cache: Kill switch state is cached in-memory with 500ms TTL for performance.
• Fail-closed: If a process previously observed an active kill switch and cannot reach the config store, it continues blocking (fail-closed from known-active state).
• Cold start: A fresh process start during a config-store outage allows traffic until it successfully reads the kill switch state.
• MCP: Governance MCP tools (br_activate_killswitch, br_deactivate_killswitch, br_get_killswitch_status, br_get_budget_status, br_get_budget_forecast) remain callable at the tool level. All other MCP tools are blocked.