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	on	Guardian processing status. Live value: on; off when skipped via X-BR-Guardian: off.
X-BR-Estimated-Cost	string	0.000210	Pre-request cost estimate in USD (6 decimals). Emitted only when the request names a priceable model — absent for model: "auto" (selection happens after this estimate; see X-BR-Estimated-Cost-Basis).
X-BR-Actual-Cost	string	0.00021020	Post-request actual cost in USD (plain numeric, no $ prefix).
X-BR-Efficiency	string	1.21	Cost efficiency ratio (estimated / actual). Conditional — emitted only when Guardian post-processing runs.
X-BR-Guardian-Overhead-Ms	string	1.2	Guardian processing latency in milliseconds (target: <5ms p95).

Routing Headers

Header	Type	Example	Description
X-BR-Routed-Model	string	anthropic/claude-sonnet-5	Actual model ID that served the request (after alias/auto resolution).
X-BR-Resolved-Model	string	anthropic/claude-sonnet-5	Model resolved from an alias or auto, before failover.
X-BR-Upstream-Model	string	claude-sonnet-5	The upstream provider model actually invoked.
X-BR-Route-Reason	string	capability-matched	Why this model was selected (when using model: "auto").
X-BR-Selection-Method	string	capability-matched	Selection engine used (capability-matched, alias, explicit).
X-BR-Selection-Reason	string	capability-matched	Human-readable selection rationale.
X-BR-Selection-Confidence	string	0.87	Confidence (0–1) in the selection.
X-BR-Complexity-Level	string	high	Classified request complexity tier.
X-BR-Complexity-Score	string	7.4	Raw complexity score (0–10).
X-BR-Models-Considered	string	12	Number of eligible models scored.
X-BR-Quality-Tier	string	frontier	Learned quality tier of the routed model.
X-BR-Failover-From	string	openai/gpt-5.5	Model that failed before failover (present only on failover).
X-BR-Failover-Path	string	openai/gpt-5.5→anthropic/...	Ordered failover chain that was walked.
X-BR-Routing-Overhead-Ms	string	2.1	Routing/selection overhead in milliseconds.

> X-BR-Model-Selected and a bare X-BR-Provider header are not emitted. Read the > routed model from X-BR-Routed-Model; provider context comes from > X-BR-Provider-Latency-Ms / X-BR-Provider-Filter.

Cost & Budget Headers

Header	Type	Example	Description
X-BR-Estimated-Cost	string	0.000210	Pre-flight cost estimate in USD (6 decimals). Absent for model: "auto"; X-BR-Estimated-Cost-Basis says why (pre-flight-token-estimate vs unpriced-auto-selection).
X-BR-Actual-Cost	string	0.00021020	Actual cost after completion in USD.
X-BR-Savings	string	0.004	Estimated USD saved vs. a naive frontier-only route.
X-BR-Routing-Savings	string	0.004	Savings attributed to auto-routing.
X-BR-Budget-Remaining	string	48.20	Remaining tenant/agent budget in USD.
X-BR-Budget-Warning	string	true	Present when the request crossed a budget threshold.
X-BR-Tokens-Remaining	string	84210	Remaining token allowance for the window.
X-BR-Total-Latency-Ms	string	1423	End-to-end latency in milliseconds.
X-BR-Provider-Latency-Ms	string	1180	Upstream provider latency in milliseconds.

Cache Headers

Header	Type	Example	Description
X-BR-Cache	string	hit	Cache result: hit, miss, bypass.
X-BR-Cache-Similarity	string	0.98	Semantic similarity score for a cache hit.
X-BR-Cache-Age	string	42	Age of the cached entry in seconds.
X-BR-Cache-Saved-Tokens	string	1200	Tokens saved by serving from cache.
X-BR-Cache-Source	string	semantic	Which cache layer served the entry.

Guardrail & Firewall Headers

Header	Type	Example	Description
X-BR-Guardrail-Status	string	pass	Guardrail verdict: pass, warn, block.
X-BR-Guardrail-Action	string	redact	Action taken (allow, redact, block).
X-BR-Guardrail-Reason	string	pii	Why the guardrail fired.
X-BR-Guardrail-PII-Warning	string	true	PII detected in inbound content.
X-BR-Tool-Firewall-Status	string	blocked	Tool firewall verdict for tool calls.
X-BR-Tool-Firewall-Reason	string	policy	Why a tool call was blocked/downgraded.
X-BR-Intent-Risk	string	0.2	Intent-risk score (0–1).

Data-Protection Headers

Header	Type	Example	Description
X-BR-Data-Policy	string	eu-only	Data-residency/processing policy applied.
X-BR-Data-Obligation	string	no-train	Per-request processing obligation enforced.
X-BR-Data-Protection-Digest	string	sha256:…	Digest of the data-protection constraints applied.
X-BR-Cache-Privacy	string	no-store	Cache privacy decision for this request.

Evidence & Governance Headers

Header	Type	Example	Description
X-BR-Evidence-Receipt	string	ev_…	Evidence-ledger receipt id for this decision.
X-BR-Evidence-Coverage	string	full	Evidence coverage level (full, partial).
X-BR-Audit-Hash	string	sha256:…	Hash chained into the tamper-evident audit ledger.
X-BR-Verdict-ID	string	vd_…	Governance verdict id.
X-BR-Policy-Match	string	deny-eu	Policy rule that matched.
X-BR-Policy-Denied	string	true	Present when a policy denied the request.
X-BR-Explain	string	rx_…	Request id to fetch full rationale at GET /v1/explain/{request_id}.

Grant & Plan Headers

Header	Type	Example	Description
X-BR-Grant-Id	string	gr_…	Grant id authorizing the request.
X-BR-Plan-Id	string	pl_…	Plan id the request executed under.
X-BR-Plan-Ceiling	string	10.00	Spend ceiling of the active plan in USD.

Mesh / A2A Headers

Header	Type	Example	Description
X-BR-Mesh-Source	string	agent-7	Originating mesh agent.
X-BR-Mesh-Trace-Id	string	mt_…	Mesh trace id across hops.
X-BR-Mesh-Hop-Count	string	2	Number of mesh hops taken.
X-BR-Mesh-Payload-Hash	string	sha256:…	Integrity hash of the mesh payload.

Agent Identity Headers

Header	Type	Example	Description
X-BR-Agent-Id	string	agent-7	Agent identity that made the request.
X-BR-Agent-Owner	string	team-core	Owner of the agent identity.
X-BR-Agent-Budget-Remaining	string	12.40	Per-agent budget remaining in USD.
X-BR-Agent-Lifecycle	string	active	Agent lifecycle state.
X-BR-Reputation-Tier	string	trusted	Graduated-trust reputation tier.

Deprecation & MNI Headers

Header	Type	Description
X-BR-Deprecation	string	Deprecation date for the routed model.
Deprecation	string	RFC 8594 deprecation header.
Sunset	string	RFC 8594 sunset date.
Link	string	RFC 8631 links to the OpenAPI spec and llms.txt.
X-BR-Request-Id	string	Correlates the request with logs, explain, and evidence.

BR emits roughly 190 X-BR-* headers across these families; the tables above list the load-bearing ones. Any header not present simply means that subsystem did not act on the request.

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-Routed-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",
    },
  },
);