> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List and retrieve models.

> GET /v1/models is the catalog, self-describing and always authoritative. Every entry carries its capabilities, limits, rates, and the parameters it accepts — so a client can decide what to send without a hard-coded table.

## Why read the catalog

The [Models](/models) page is a snapshot of the catalog at the time it was generated. The
endpoint is the catalog. Models are added, retired and repriced without an API version bump
([Reliability](/reliability)), so anything that picks a model at runtime — a router, a
model-picker UI, a capability check before sending an image — should read it here rather
than ship a copy.

This endpoint is **unauthenticated** and cacheable (`cache-control: public, max-age=300`).
Every SDK calls it at client-init; it costs you nothing and draws no usage.

## List

```http theme={null}
GET /v1/models
```

```sh theme={null}
curl https://api.sideren.io/v1/models
```

```json title="Response (OpenAI shape)" theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "@sdn/gpt-oss-120b",
      "object": "model",
      "created": 1719792000,
      "owned_by": "sideren",
      "delivery": "exact",
      "aliases": ["sdn-gpt-oss-120b", "gpt-oss-120b"],
      "tier": "workhorse",
      "context_window": 128000,
      "max_output": null,
      "capabilities": {
        "tools": true,
        "reasoning": true,
        "vision": false,
        "documents": false
      },
      "supported_parameters": [
        "messages", "system", "max_tokens", "stream", "temperature",
        "top_p", "frequency_penalty", "presence_penalty", "seed", "stop",
        "parallel_tool_calls", "tools", "tool_choice", "forced_tool_choice",
        "reasoning"
      ],
      "native_wires": ["openai-chat"]
    }
  ]
}
```

### Fields

| Field | Notes |
| - | - |
| `id` | The public id — what you put in `model`. Closed-weight models are listed by their plain name (`gpt-6.1-sol`), open-weight models as `@sdn/<name>` (`@sdn/gpt-oss-120b`). |
| `aliases` | The older spellings and other strings that resolve to this model (`sdn-gpt-oss-120b`, the bare `gpt-oss-120b`). All of them keep working. See [Model routing](/guides/model-routing). |
| `tier` | The catalog tier this model sits in (`frontier`, `premium`, `coding-flagship`, `workhorse`, …), matching the groupings on [Models](/models). |
| `context_window` | Total tokens the model accepts. |
| `max_output` | Output ceiling, or `null` when the model publishes none. |
| `capabilities.tools` | Accepts `tools` / `tool_choice`. |
| `capabilities.reasoning` | Has a reasoning mode. See [Reasoning](/guides/reasoning). |
| `capabilities.vision` | Reads images. See [Vision](/guides/vision). |
| `capabilities.documents` | Accepts document/PDF input. |
| `pricing_usd_per_mtok` | Per-million-token rates: `input`, `output`, and `cached_input` — `null` when the model publishes no cached rate, which is also when repeated context earns no discount ([Prompt caching](/guides/prompt-caching)). What a request takes from your plan is counted in [credits](/plans). |
| `delivery` | `exact` when the id has its own same-model placement; `optimized` when it is an explicitly routed compatibility id. The field never reveals the upstream provider or physical fallback. |
| `supported_parameters` | The parameter names this model honors. A capability-aware client should check here before sending `response_format` or a forced `tool_choice`. |
| `native_wires` | Protocols this model is served over natively. Informational — every model works on every endpoint. |
| `output_dimensions` | Embedding rows only: the width of the vector they produce. |

<Note>
  Providers and upstream deployment names are never in the response. One row is one
  *logical* model; which backend serves it is an implementation detail that can change
  mid-flight, which is exactly what makes [continuity](/reliability) possible.
</Note>

### Anthropic shape

Send an `anthropic-version` header — as every Anthropic SDK does — and the same endpoint
answers in Anthropic's list envelope instead, so `client.models.list()` type-checks:

```json theme={null}
{
  "data": [
    {
      "type": "model",
      "id": "gemini-3.8-flash",
      "display_name": "gemini-3.8-flash",
      "created_at": "2024-07-01T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "first_id": "gemini-3.8-flash",
  "last_id": "@sdn/plamo-embed-1b"
}
```

### Filtering

`?wire=native|anthropic|openai|responses` keeps only the models served on that wire
(`native` means the wire of the endpoint you are calling). An unknown value is a `400`.

### In PAYG mode

With `x-sideren-payment-mode: payg` (see [Headers](/headers#request-headers)) the list
requires authentication, is not cached (`cache-control: private, no-store`), keeps only
exactly-delivered models, and shows the rates that apply in PAYG mode.

## Retrieve one

```http theme={null}
GET /v1/models/{id}
```

Accepts the public id or any older spelling — so `@sdn/gpt-oss-120b`, `sdn-gpt-oss-120b`,
`gpt-oss-120b` and any other alias all resolve. The `@` and `/` in a public id can go in the
path raw or URL-encoded (`%40sdn%2Fgpt-oss-120b`). Returns the same entry shape as the list
(or the Anthropic per-item shape with `anthropic-version` set).

```sh theme={null}
curl https://api.sideren.io/v1/models/@sdn/gpt-oss-120b

# the same request, URL-encoded
curl https://api.sideren.io/v1/models/%40sdn%2Fgpt-oss-120b
```

An unknown id returns `404`:

```json theme={null}
{ "error": { "type": "not_found", "message": "no such model: nope" } }
```

<Note>
  Retrieve is a **validity check**, so it is deliberately stricter than the chat endpoints:
  the foreign-name compatibility handles that let `gpt-4o` work in a chat request are not
  resolved here. If you need to know what a foreign id maps to, send it to a chat endpoint
  and read the model back off the response.
</Note>

## From the setup helper

```sh theme={null}
npx sideren models
```

Prints the catalog straight from this endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.