Headers Reference

All X-BR-* request and response headers.

Request Headers

These headers control BrainstormRouter behavior on a per-request basis.

Header	Type	Description
Authorization	Bearer	Required. API key (br_live_... or br_test_...).
X-BR-Guardian: off	string	Skip Guardian intelligence processing.
X-BR-Skip-Memory: true	string	Skip memory read/write for this request. Useful for stateless agents.
X-User-Id	string	Identify the end-user or agent. Used for per-agent budget enforcement. Falls back to body.user.
X-Conversation-Id	string	Thread requests into a conversation. Also accepted as conversation_id in the request body.

Response Headers

Returned on POST /v1/chat/completions responses.

Guardian Headers

Header	Type	Example	Description
X-BR-Guardian-Status	string	pass	Guardian processing result: pass, warn, block, off.
X-BR-Estimated-Cost	string	0.0023	Pre-request cost estimate in USD.
X-BR-Actual-Cost	string	0.0019	Post-request actual cost in USD.
X-BR-Efficiency	string	1.21	Cost efficiency ratio (estimated / actual). Values >1 mean under-budget.
X-BR-Guardian-Overhead-Ms	string	1.2	Guardian processing latency in milliseconds (target: <5ms p95).

Routing Headers

Header	Type	Example	Description
X-BR-Model	string	claude-sonnet-4-5-20250514	Actual model ID used (after alias/auto resolution).
X-BR-Provider	string	anthropic	Provider that served the request.
X-BR-Route-Reason	string	auto:complexity-high	Why this model was selected (when using model: "auto").

Cost & Usage Headers

Header	Type	Example	Description
X-Model-Router-Cost	string	0.0019	Total cost for this request in USD.
X-Model-Router-Latency-Ms	string	1423	End-to-end latency in milliseconds.

Using Headers with OpenAI SDKs

from openai import OpenAI

client = OpenAI(
    base_url="https://api.brainstormrouter.com/v1",
    api_key="br_live_...",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "X-BR-Skip-Memory": "true",
        "X-User-Id": "agent-research-01",
    },
)

# Access response headers
print(response._response.headers.get("X-BR-Actual-Cost"))
print(response._response.headers.get("X-BR-Model"))

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.brainstormrouter.com/v1",
  apiKey: "br_live_...",
});

const response = await client.chat.completions.create(
  {
    model: "auto",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "X-BR-Skip-Memory": "true",
      "X-User-Id": "agent-research-01",
    },
  },
);