Request Headers

Complete reference for X-Majordomo-* headers.

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

Request headers

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. If omitted, the gateway infers from 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- (except -Key and -Provider) is stored as metadata on the request log.

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.

Full example

Python (OpenAI)

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

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.