Request Headers

All Majordomo-specific behavior is controlled via HTTP headers. Standard provider SDK headers (Authorization, Content-Type, etc.) pass through unchanged.

Header	Required	Description
`X-Majordomo-Key`	Yes	Your Majordomo API key (`mdm_sk_...`). Identifies the account, associates the request with your usage log.
`X-Majordomo-Provider`	No	Explicit provider override, or `majordomo` to opt into provider routing. Required for OpenAI-compatible providers, which share the OpenAI request path. If omitted, the gateway infers from the request path.

Provider values

Value	Notes
`openai`
`anthropic`
`gemini`
`azure`
`bedrock`	Requires a region, via `X-Majordomo-Bedrock-Region` or a `bedrock-runtime.<region>.amazonaws.com` host.
`bedrock-mantle`	Anthropic Messages API surface.
`fireworks`, `together`, `deepseek`, `moonshot`, `baseten`, `nebius`, `deepinfra`, `novita`	OpenAI-compatible. Set this header explicitly, since they share the OpenAI request path.
`majordomo`	Not a provider. Opts the request into provider routing, which picks the cheapest healthy provider that can serve the requested model.

Provider inference

If X-Majordomo-Provider is not set, the gateway infers the provider:

Path prefix	Inferred provider
`/v1/chat/completions`	OpenAI
`/v1/messages`	Anthropic
`/v1beta/models`	Gemini

Set the header explicitly when your path doesn’t match the defaults, or when routing the same path to multiple providers.

Data policy headers

These constrain which provider endpoints routing may select. They apply to routed requests; a request that pins a provider goes where you sent it.

Header	Values	Description
`X-Majordomo-ZDR`	`1`, `true`, `yes`, `on`, `require`	Only select endpoints with a zero-data-retention guarantee.
`X-Majordomo-Data-Collection`	`deny`	Only select providers that do not collect request data.

Most restrictive wins. Each request’s policy is the union of three layers: the deployment default, the per-API-key floor (require_zdr / require_no_data_collection, see API Keys), and these headers. A header can add a requirement but never remove one, so a key configured to require ZDR cannot opt out of it per request. Both fail closed. An endpoint with no explicit guarantee never satisfies a requirement. If nothing qualifies, the request returns 502 rather than falling back to a non-compliant provider.

Response headers

The gateway sets these on the response when the corresponding behavior applied.

Header	Set when	Description
`X-Majordomo-Routed-Provider`	Request was routed	The provider that served it.
`X-Majordomo-Routed-Model`	Request was routed	The provider-native model id your slug was rewritten to.
`X-Majordomo-Credential-Source`	Request was routed	`own` if your provider key paid, `platform` if Majordomo’s did.
`X-Majordomo-Deprecated-Model`	A deprecated model was requested and the key’s behavior is `warn`	The deprecated model you asked for.
`X-Majordomo-Deprecated-Replacement`	Same as above	The model actually used.

Metadata headers

Any header prefixed with X-Majordomo- is stored as metadata on the request log, except the reserved headers that carry dedicated behavior: X-Majordomo-Key, X-Majordomo-Provider, X-Majordomo-Provider-Alias, X-Majordomo-Client, the data policy headers (X-Majordomo-ZDR, X-Majordomo-Data-Collection), and the agent run tracking headers (X-Majordomo-Trace-Id, X-Majordomo-Span-Path, X-Majordomo-Span-Name).

X-Majordomo-Feature: document-review
X-Majordomo-Team: legal
X-Majordomo-Environment: production
X-Majordomo-User-Id: user_123

Metadata is stored in the raw_metadata JSONB column on llm_requests. Keys can be promoted to the indexed_metadata column (GIN-indexed) via the dashboard for fast @> queries. Naming convention: The X-Majordomo- prefix is stripped and the remainder is stored as-is. X-Majordomo-Feature becomes Feature in the metadata map. No schema changes required. New keys are stored immediately. You can add metadata dimensions without touching the database.

Recommended metadata dimensions

Header	Example	Use for
`X-Majordomo-Feature`	`chat`, `summarizer`	Per product feature
`X-Majordomo-Team`	`platform`, `data`	Per team
`X-Majordomo-Environment`	`production`, `staging`	Per environment
`X-Majordomo-User-Id`	`user_abc123`	Per end user (opaque ID, not PII)
`X-Majordomo-User-Tier`	`free`, `pro`, `enterprise`	Per pricing tier
`X-Majordomo-Experiment`	`model-test-v2`	Per A/B test

See Cost Attribution for query examples.

Agent run tracking

When one logical task, a conversation or an agent/workflow run, makes several LLM calls, these headers group those calls into a single run so the dashboard can show a rolled-up cost and a nested waterfall instead of unrelated requests. They are reserved (consumed by the gateway, not stored in raw_metadata) and stored as first-class columns on llm_requests.

Header	Required	Description
`X-Majordomo-Trace-Id`	To join a run	One id per conversation / agent run. Generate it once at the start of the run and send it on every LLM call in that run (any opaque string).
`X-Majordomo-Span-Path`	No	`/`-joined names of the ancestor steps from the run root down to this call’s parent, e.g. `planner/tool:search_db`. Omit to hang the call directly under the run root. `/` is the reserved separator, so percent-encode a literal `/` inside a step name.
`X-Majordomo-Span-Name`	No	Label for this call in the waterfall. Defaults to the model name.

Graceful degradation: a trace id alone gives a flat run rollup (all the run’s calls + total cost); adding a span path gives the nested waterfall (which tool/agent step drove which calls, and what each cost). No SDK is required. Any client that can set headers works.

X-Majordomo-Trace-Id: run_7f3a
X-Majordomo-Span-Path: planner/tool:search_db
X-Majordomo-Span-Name: summarize

See Agent Run Tracking for the full walkthrough.

Full example

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.gomajordomo.com/v1",
    api_key="your-openai-key",
    default_headers={
        "X-Majordomo-Key": "mdm_sk_your_key_here",
        "X-Majordomo-Feature": "document-review",
        "X-Majordomo-Team": "legal",
        "X-Majordomo-Environment": "production",
    }
)

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.gomajordomo.com",
    api_key="your-anthropic-key",
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "X-Majordomo-Key": "mdm_sk_your_key_here",
        "X-Majordomo-Feature": "support-chat",
        "X-Majordomo-User-Id": "user_123",
    }
)

curl -X POST https://gateway.gomajordomo.com/v1/chat/completions \
  -H "Authorization: Bearer your-openai-key" \
  -H "X-Majordomo-Key: mdm_sk_your_key_here" \
  -H "X-Majordomo-Feature: chat" \
  -H "X-Majordomo-Team: product" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Header forwarding

Headers prefixed with X-Majordomo- are not forwarded to upstream providers. They are consumed by the gateway and stripped before the request is proxied. All other headers (including custom X-* headers your provider supports) are forwarded as-is.

Getting Started

How It Works

Connect Your Code

Track & Analyze

Control

Enterprise

Reference

Request Headers

Request headers

Provider values

Provider inference

Data policy headers

Response headers

Metadata headers

Recommended metadata dimensions

Agent run tracking

Full example

Header forwarding

​Request headers

​Provider values

​Provider inference

​Data policy headers

​Response headers

​Metadata headers

​Recommended metadata dimensions

​Agent run tracking

​Full example

​Header forwarding

Request headers

Provider values

Provider inference

Data policy headers

Response headers

Metadata headers

Recommended metadata dimensions

Agent run tracking

Full example

Header forwarding