The /v1/models endpoint returns the public model names that are configured in your rolter.toml and accessible to the authenticated virtual key. You can use this endpoint to discover which model names to pass in the model field of chat, completion, or messages requests.
What is returned#
The response lists every model name this gateway accepts in a model field, in three forms:
| Id | owned_by | What it is |
|---|---|---|
gpt-4o | rolter | a route name from your configuration. A route configured with model = "gpt-4o" that targets the upstream model gpt-4o-2024-11-20 appears as gpt-4o — the upstream id stays an internal concern of the route |
openai-edge/gpt-4o | the provider’s name | a provider-pinned address: this provider, this upstream model, no cross-provider fan-out |
edge-fleet/gpt-4o | the group’s name | a provider-group address, balanced across the group’s members |
When virtual keys are configured, the list is filtered to the models that the authenticated key’s models allow-list permits. A key configured with models = [] (empty) can see all of them. A key created in the dashboard or through the API only ever sees its own organization’s routes, providers and provider groups, and a route an admin narrowed to one project is listed only for that project’s keys.
How the provider-pinned list is built#
A provider-pinned address works for any model the provider actually serves, not only the ones your routes mention. To list them, Rolter periodically reads the model catalogue each provider returns to its free model-list request and caches it.
The refresh runs by default, every 15 minutes, and does not need active health checks. Set [health] catalogue_interval_secs = 0 to turn it off; the provider-pinned entries are then derived from your route targets alone, so a provider that serves more models than your routes name will under-report them. A newly added provider is listed within about half a minute. This changes only what is listed: provider-slug/model routes either way, so an address you know works even when it is not in the list.
At most 200 catalogued models are listed per provider, so one aggregator with a several-hundred-model catalogue cannot bury the rest of your fleet. Models named by a route target are always listed, regardless of that cap.
Rolter also exposes a built-in fake-llm model that responds locally without forwarding to any upstream. It appears in the model list unless a route your key can use shadows it with the same name. A route another organization owns never hides it, and the dashboard and API refuse fake-llm as a route name; only the operator can replace it, from rolter.toml. It is useful for testing authentication and connectivity without incurring upstream costs.
Request#
GET /v1/models
Headers#
Example#
Response#
Always "list".
Array of model objects, one per accessible model name.
A route’s description is never listed: it is a free-text note for your team and may hold internal routing notes. Provider-pinned and group addresses carry no metadata, because the gateway does not know their upstream model’s properties.
Virtual key filtering#
If your key is scoped to a subset of models, only those appear in the response. For example, a key configured as:
returns only the gpt-4o entry, even if claude and llama routes are defined. Requesting a model outside the key’s allow-list on an inference endpoint returns 403 Forbidden.
Use this endpoint from your application at startup to validate that the expected model routes are reachable with the configured key before serving user traffic.