Models

A model is identified by an author/model id (the same scheme OpenRouter uses). The catalog aggregates every model offered by active providers. You pick the model, and provider routing decides which provider fulfills it.

Model ids

You can pass either form as the model field in a request body:

The author/model id refers to the model author (e.g. openai, anthropic), not to the provider fulfilling the request. Providers are addressed separately through the provider object.

Dot and hyphen forms

Some models write their version number with a dot upstream and a hyphen in the provider-native id. Onlist publishes one form as the public id and accepts the other as an alias, so both resolve to the same model:

This matches OpenRouter, which publishes the same models under the dot form. Requesting the hyphen form works and is not deprecated; a model page opened at the hyphen URL redirects to the published one. If you persist model ids, persist canonical_slug: it does not move when the published form does.

Listing models

GET /v1/models returns the catalog in the OpenAI/OpenRouter list shape. It is public, no authentication required, and is cached for about 60 seconds. There is one entry per (author, model) aggregated across active, ready listings.

curl https://onlist.io/v1/models

A response looks like this:

{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-opus-4.8",
      "name": "Anthropic: Claude Opus 4.8",
      "owned_by": "anthropic",
      "canonical_slug": "anthropic/claude-opus-4-8",
      "created": 1780680536,
      "context_length": 1000000,
      "pricing": { "prompt": "0.0000030000", "completion": "0.0000150000" },
      "supported_parameters": ["tools", "reasoning", "structured_outputs"]
    }
  ]
}

A few honest details about the fields:

• pricing.prompt / pricing.completion are USD-per-token decimal strings (so "0.0000030000" is $3.00 per million prompt tokens).
• name is the human-readable display label (Anthropic: Claude Opus 4.8), not a copy of id.
• canonical_slug is the provider-native form of the id. It stays put when id is published under an alias form, so it is the safer value to store.
• created is the listing's created_at (when a provider listed the model on Onlist), not the model's release date, a deliberate divergence from OpenRouter.
• The response carries an X-Onlist-Catalog-Version: 1 header pinning the catalog shape.

The onlist/auto default

Model variant suffixes

A : suffix on a model id means one of two things, and Onlist reads them the way OpenRouter does. Only the last : segment is inspected.

Routing shortcuts never change which model you get. They are stripped from the id and only reorder the eligible providers:

# Route to the cheapest provider for this model
curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o:floor", "messages": [{"role": "user", "content": "hi"}]}'

Static variants are separate models, not options. Every other suffix, including :free, :batch, :thinking and anything Onlist does not recognize, stays in the model id and is routed to its own listing: deepseek/deepseek-v4:thinking and deepseek/deepseek-v4 are two different products.

Next steps

• Provider routing: Choose which provider fulfills a model: only, sort, allow, max_price.
• Streaming: Stream responses over Server-Sent Events.
• Usage & cost: Token usage, and where cost actually lives.
• OpenAPI spec: Full request and response schemas, including GET /v1/models (YAML download).