Onlist

Quickstart

Onlist exposes an OpenAI- and OpenRouter-compatible /v1 surface. You can use the official Onlist SDKs (Python and JS/TS), or any OpenAI-compatible client with a base URL swap. Request and response bodies stay the same either way.

This page gets you from zero to a first chat completion against openai/gpt-4o.

Before you start

  1. Get an API token. Sign in to the buyer dashboard at onlist.io and create a token. It is a plain bearer token — there is no sk-or- prefix (a leading sk- is tolerated and stripped). Top up your wallet first: billing is prepaid, and each settled request debits your balance.

  2. Point your SDK at Onlist. Set the base URL to https://onlist.io/v1 and use your token as the API key. The full endpoint is https://onlist.io/v1/chat/completions.

  3. Make your first chat completion. Send a standard OpenAI Chat Completions request, as shown below.

Your first request

The examples below send a minimal chat completion to openai/gpt-4o. Replace YOUR_ONLIST_TOKEN with the token from your dashboard.

curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "user", "content": "Hello from Onlist!" }
    ]
  }'

The response is the standard OpenAI chat completion shape. The usage object reports prompt_tokens, completion_tokens, and total_tokens.

Caution

Unlike OpenRouter, Onlist does not return usage.cost in the response body. To see what a request cost, correlate it by the X-Onlist-Route-Id response header in the buyer dashboard. See Usage & cost for details.

Model ids

Model ids take the form author/model (for example openai/gpt-4o) or a bare name (gpt-4o). Call GET /v1/models to list the catalog, or browse it on the Models page.

Optional: streaming and routing

Two features are entirely optional — the request above works without either.

  • Streaming. Set "stream": true to receive Server-Sent Events ending with data: [DONE]. Note that stream_options.include_usage is forced to true while streaming so a terminal usage chunk is emitted for settlement. See Streaming.
  • Provider routing. Add an optional provider object to the JSON body to steer which provider fulfills the request (pin, sort, allow/deny, price caps). See Provider routing.

Next steps

  • SDKs — Install the official Python or JS/TS SDK for zero-config usage with ONLIST_API_KEY and a typed marketplace API.
  • Migrate from OpenRouter — Change your base URL and token. See what's identical and where Onlist differs.
  • Provider routing — The optional provider object: pin a provider, sort by price, set caps.
  • Authentication — Bearer tokens, header normalization for Anthropic and Gemini SDKs.
  • OpenAPI spec — Full request and response schemas for every endpoint (YAML download).