> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomajordomo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`, `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](#agent-run-tracking) headers (`X-Majordomo-Trace-Id`, `X-Majordomo-Span-Path`, `X-Majordomo-Span-Name`).

```http theme={null}
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](/guides/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.

```http theme={null}
X-Majordomo-Trace-Id: run_7f3a
X-Majordomo-Span-Path: planner/tool:search_db
X-Majordomo-Span-Name: summarize
```

See [Agent Run Tracking](/guides/agent-runs) for the full walkthrough.

## Full example

<CodeGroup>
  ```python Python (OpenAI) theme={null}
  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",
      }
  )
  ```

  ```python Python (Anthropic) theme={null}
  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",
      }
  )
  ```

  ```bash curl theme={null}
  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"}]}'
  ```
</CodeGroup>

## 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.