skip to content

What do OpenRouter's optional HTTP-Referer and X-Title request headers do?

level: middleimportance: should knowfreq 40%

answer

  1. Two optional headers, no functional effect
  2. Metadata about your app, not your identity
  3. Feeds the public app rankings
  4. One is a URL, one is a name
  5. Watch the single-r spelling of Referer

basics

~20 s

They are optional attribution headers: HTTP-Referer carries your app's URL and X-Title its display name, so requests are credited to your app on OpenRouter's public model rankings and in your own dashboard. They are not authentication and do not affect routing.

solid answer

~40 s

Both are optional metadata you attach to a chat completions call. `HTTP-Referer` should hold your site or app URL and `X-Title` a human-readable app name; OpenRouter uses them to attribute traffic to your application in its public leaderboards of which apps use which models, and to label your own usage view. Omitting them changes nothing functionally — the request still authenticates with your bearer token, still routes the same way, and is still billed the same. They carry no security meaning: anyone can send any value, so never treat them as identity or use them to gate anything. Note the spelling: the header is `HTTP-Referer`, matching the misspelling baked into the HTTP standard's own `Referer` header, so `HTTP-Referrer` with two r's is simply a different header that will be ignored.

code

python · 10 lines
python
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="<OPENROUTER_API_KEY>",
    default_headers={
        "HTTP-Referer": "https://example.com",
        "X-Title": "Example Support Bot",
    },
)

go deeper

for a junior

Know that both headers are optional and purely informational: a URL and an app name that let OpenRouter credit your app. Say plainly that leaving them out still returns a normal response.

for a middle

Explain what they buy you — attribution on the public app rankings and readable labelling of your own traffic — and be precise that the bearer token, not these headers, is the credential.

for a senior

Show operational care: set them as client-level default headers, keep the value stable across call sites, and keep anything sensitive out of a field that surfaces publicly.

for a principal

Treat them as a policy question. Decide as an organisation whether your app should appear in public usage rankings at all, and make sure attribution metadata never becomes a channel that leaks internal topology or customer identifiers.

## What they are OpenRouter's chat completions endpoint accepts two optional headers alongside the mandatory `Authorization: Bearer <key>`: - `HTTP-Referer` — the URL of the site or app making the call. - `X-Title` — a short human-readable name for that app. Neither is required. A request without them succeeds exactly as one with them. ## Why they exist OpenRouter publishes rankings of which applications drive traffic to which models. Those headers are how a request gets attributed to an app in that view, and they also give you a readable label for your own traffic instead of an opaque key id. For a public product it is free distribution — your app appears next to the models it uses. For an internal service it is a convenient way to distinguish "the batch summariser" from "the chat widget" when both share credentials. ## What they are not This is where interview answers go wrong. They are **not authentication**. The bearer token is the credential. The headers are self-asserted strings; any client can send any value, and OpenRouter does not verify that the URL in `HTTP-Referer` is yours in the way a browser same-origin check would. Nothing about your account's permissions, quota, or key scope derives from them. They are **not routing or model selection**. They do not steer the request to a provider, change which upstream serves it, or alter pricing. Selecting providers and models is done with the request body, not with headers. They are **not sent automatically** by an OpenAI SDK. Server-side HTTP clients do not populate `Referer` on their own; you must add the headers explicitly, usually as default headers on the client so every call carries them. ## The spelling trap The HTTP specification's referrer header has been misspelled `Referer` since 1996, and OpenRouter's header follows that convention: `HTTP-Referer`, one `r` in the middle. Sending `HTTP-Referrer` sends a header nobody reads, and your traffic silently goes unattributed. This is a favourite detail to probe because it separates people who have actually wired the integration from people who have read about it. ## Practical guidance Set both once, at client construction time, as default headers rather than per call — that way every code path is attributed consistently and you cannot forget one. Use a stable value: rewriting `X-Title` per environment fragments your own analytics, so prefer one product name and distinguish environments some other way, such as separate API keys. Put a real, resolvable URL in `HTTP-Referer`; a placeholder like `http://localhost` in production traffic is noise. And because the values are public-facing on rankings, never embed anything sensitive — no internal hostnames, tenant identifiers, user emails, or tokens. Treat them as marketing copy that happens to travel in a header. ## Relation to the rest of the API These headers sit outside the normalisation the gateway performs on the request body: they are consumed by OpenRouter itself and never forwarded to the upstream vendor as part of the model call. That is worth saying explicitly, because a natural worry is whether your app's URL leaks to every provider you touch. The provider sees the translated prompt, not your attribution metadata.

  • If a request omits both headers, what changes?
    Functionally nothing. The call authenticates on the bearer token, routes identically, returns the same response and is billed the same. The only difference is that the traffic is not attributed to a named app in OpenRouter's public rankings or labelled in your own usage view, so it shows up as unattributed.
  • Could you use HTTP-Referer to restrict who may use your key from a browser?
    No. The header is self-asserted by whoever makes the request, so anyone holding the key can send whatever value they like; it is metadata, not an access control. The real lesson is not to put an OpenRouter key in a browser at all — proxy calls through your own backend, where the secret stays server-side and you can apply real per-user authorisation.
  • Where would you set these headers in a typical integration?
    As default headers on the HTTP client or SDK instance, so every request inherits them. OpenAI-compatible SDKs expose a default-headers option at construction time; setting them there beats sprinkling them across call sites, where one forgotten path leaves a slice of traffic unattributed and inconsistent.

saying these in an interview costs you the question

  • Claiming the headers authenticate or authorise the request
  • Thinking they influence which provider serves the call
  • Spelling it HTTP-Referrer with two r's
  • Assuming the SDK sends them automatically
  • Putting internal or user-identifying data in X-Title

context

resolving links…