App Attribution

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

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 CLI agents are recognized by their User-Agent alone — Claude Code and Codex traffic is attributed even when no HTTP-Referer is sent.

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.

Categories

Categories are optional labels used for filtering on the rankings. Values outside the whitelist are silently ignored, and at most 2 are accepted per request; new values accumulate onto your app over time.

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, and X-OpenRouter-Categories 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.