App Attribution | Onlist Docs

Every request you send to Onlist can carry a few optional headers that identify which app or agent it came from. Apps that opt in appear on the public App & Agent Rankings with a detail page showing real usage stats — free visibility for your tool, driven by actual traffic, the same mechanism OpenRouter uses for its Top Apps page.

Attribution is entirely optional. Requests without these headers behave identically; they are simply not counted toward any app.

Opt in with two headers

Header	Role	Notes
`HTTP-Referer`	App identity	A URL that identifies your app. This becomes the app's canonical identity on the rankings.
`X-Title`	Display name	Human-readable name shown on the rankings. Optional but recommended.
`X-OpenRouter-Categories`	Categories (optional)	Comma-separated, up to 2 per request, values from the whitelist below.
`X-OpenRouter-App-Visibility`	Visibility (optional)	`hidden` keeps a new app off the public rankings and app pages. Only applies when the request first creates the app.

OpenRouter compatibility: X-OpenRouter-Title is accepted as an alias for X-Title (and takes precedence when both are present). If your app already sends attribution headers to OpenRouter, they work on Onlist unchanged.

curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://myapp.example" \
  -H "X-Title: MyApp" \
  -H "X-OpenRouter-Categories: cli-agent" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Some well-known public clients are recognized by their User-Agent alone, so their traffic is attributed even without HTTP-Referer: Claude Code, Codex (CLI, desktop app and IDE extension), opencode, the Janitor AI iOS app and GitHub Copilot Chat. Any other tool, including your own, is listed only when it sends the headers above. Onlist never puts an app on the rankings just because it recognizes an unfamiliar User-Agent.

Hidden apps

Send X-OpenRouter-App-Visibility: hidden if you want your traffic attributed without a public listing. The app still gets an identity and its usage is still counted, but it is excluded from the rankings, the ranking dataset and public app pages.

The header only takes effect on the request that first creates the app. After that it changes nothing: a later request cannot make a hidden app public, and nobody can hide an app that is already listed. To change an existing app's visibility, open a ticket. The header is ignored for the clients recognized by User-Agent.

How app identity works

The HTTP-Referer URL is normalized into a canonical key. Two requests attribute to the same app when their normalized keys match:

Host is lowercased, IDN domains are converted to punycode, a leading www. is stripped, and default ports (80/443) are dropped.
Scheme, query string, and fragment are dropped; the path is kept (so https://acme.example/tool-a and https://acme.example/tool-b are two different apps).
Trailing slashes are removed.
localhost (and 127.0.0.1 / ::1 / *.localhost) is only tracked when an X-Title is present.
Bare tokens without a dot, and non-loopback IP literals, are never tracked.

Group	Subcategories
`coding`	`cli-agent`, `ide-extension`, `cloud-agent`, `programming-app`, `native-app-builder`
`creative`	`creative-writing`, `video-gen`, `image-gen`, `audio-gen`
`productivity`	`writing-assistant`, `general-chat`, `personal-agent`, `legal`
`entertainment`	`roleplay`, `game`

What appears on the rankings

Threshold. An app appears on the public rankings once its usage in the selected window reaches 10,000 tokens. Below that, traffic is still attributed and counted; the app is just not displayed yet.
Ranking metric. Total tokens, OpenRouter-style: prompt tokens (including cached) plus completion tokens. Rankings refresh within about 5 minutes of traffic.
Windows. All windows are UTC-day based. The Top sort is live and includes the current (partial) day. The Trending sort compares complete days only: current window versus the average of the 3 preceding equal windows, and only apps with positive excess growth qualify.
Metadata. Once an app crosses the same 10K-token threshold, Onlist fetches its homepage og:title / og:description (roughly monthly) for the display name and description, cleaning SEO taglines down to the product name. Sending a clear X-Title is still the most reliable way to control your name before metadata is fetched.
Machine-readable data. The same rankings are available as a public dataset at GET /api/v1/datasets/app-rankings, format-compatible with OpenRouter's.

Privacy

Attribution headers never reach providers. HTTP-Referer, X-Title, X-OpenRouter-Title, X-OpenRouter-Categories, and X-OpenRouter-App-Visibility are stripped from your request before it is forwarded upstream, so the provider serving you cannot see which app the traffic came from.

Claiming and corrections

Curated app pages (locked name, description, and a friendly /apps/<slug> URL) are maintained by the Onlist team. To claim your app's page, correct its name or description, or report a listing problem, open a ticket.