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: `openai`, `anthropic`, `gemini`, `bedrock`, `fireworks`, `together`, `deepseek`. Required for OpenAI-compatible providers (Fireworks, Together, DeepSeek), which share the OpenAI request path. If omitted, the gateway infers from the request path.

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.

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, 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 — 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 inference

Metadata headers

Recommended metadata dimensions

Agent run tracking

Full example

Header forwarding

​Request headers

​Provider inference

​Metadata headers

​Recommended metadata dimensions

​Agent run tracking

​Full example

​Header forwarding

Request headers

Provider inference

Metadata headers

Recommended metadata dimensions

Agent run tracking

Full example

Header forwarding