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

# Models and providers

> Understand catalog model IDs, provider profiles, modalities, capabilities, prices, and parameter support.

The model catalog is the routing contract between management and inference. Query the deployed catalog instead of hard-coding the repository snapshot:

```bash theme={null}
airmux providers list -f json
airmux models list -f json
```

## Inference model discovery

`GET /inf/v1/models` returns `{"object": "list", "data": [...]}`. `GET /inf/v1/models/{model_id}` returns one model object.
Both endpoints require an active workspace inference key and work with the OpenAI SDK's `models.list()` and
`models.retrieve()` methods. Model IDs containing slashes are supported.

| Field                       | Meaning                                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `id`                        | Gateway model ID to use in inference requests                                               |
| `object`                    | Always `model`                                                                              |
| `created`                   | Unix timestamp of the catalog snapshot's publication, not the upstream model's release date |
| `owned_by`                  | Configured provider routing name                                                            |
| `gateway.context_window`    | Maximum context tokens                                                                      |
| `gateway.max_output_tokens` | Output cap, or `null` when unknown                                                          |
| `gateway.input_modalities`  | Declared supported input kinds                                                              |
| `gateway.output_modalities` | Declared supported output kinds                                                             |
| `gateway.capabilities`      | Declared supported gateway features                                                         |
| `gateway.parameter_support` | Explicit parameter support; absent parameters are unknown                                   |

The list is sorted by model ID and contains models from the caller's organization bundle with a configured credential
reference in an eligible platform, organization, or workspace scope. Workspace and selected-key policies apply, including
model/provider allowlists, price ceilings, unconditional denials, model-matched denials, and credential-access rules.
An unknown or hidden model returns the same `404` response. Missing or invalid inference keys return `401`; discovery
returns `503` until a bundle is available. Errors use the OpenAI error shape and responses disable caching.

Discovery reads the admitted bundle without database queries, provider calls, or secret resolution. It describes
configured eligibility, not live credential health. Rules conditioned on streaming or request capabilities, strict
parameter checks, request limits, and fallback execution apply during inference. Catalog modalities do not add new
inference endpoints; current content support is described below.

## Provider entries

| Field             | Meaning                                   |
| ----------------- | ----------------------------------------- |
| `provider_id`     | Stable lowercase routing name             |
| `kind`            | Egress adapter family                     |
| `base_url`        | Upstream API base URL                     |
| `param_aliases`   | Canonical parameter to provider spelling  |
| `accepted_params` | Known accepted top-level extras           |
| `params_closed`   | Whether undeclared extras must be dropped |

The shipped taxonomy currently includes Anthropic, Cerebras, DeepSeek, Fireworks, Groq, Mistral, OpenAI, Together, and
xAI provider entries. The deployed catalog is authoritative and may differ after a taxonomy update.

## Model entries

| Field                        | Meaning                                      |
| ---------------------------- | -------------------------------------------- |
| `model_id`                   | Caller-facing `provider/model` identifier    |
| `provider_id`                | Provider route                               |
| `upstream_model`             | Model name sent to the provider              |
| `egress_kind`                | Optional model-level adapter override        |
| `input_price_per_mtok`       | USD per million input tokens                 |
| `output_price_per_mtok`      | USD per million output tokens                |
| `cache_read_price_per_mtok`  | USD per million cache-read tokens            |
| `cache_write_price_per_mtok` | USD per million cache-write tokens           |
| `context_window`             | Maximum context tokens                       |
| `max_output_tokens`          | Output cap used for reconciliation           |
| `input_modalities`           | Supported input kinds                        |
| `output_modalities`          | Supported output kinds                       |
| `capabilities`               | Supported gateway features                   |
| `parameter_support`          | Explicit `supported` or `unsupported` values |

Modalities are `text`, `image`, `audio`, `video`, and `pdf`. Current inference content supports text, images, and PDFs;
catalog entries can still describe the broader vocabulary.

Capabilities are `streaming`, `tools`, `reasoning`, and `structured_output`. `airmux` derives requirements from the
request and rejects a route with a missing capability.

## Update the catalog

The repository taxonomy is generated from the model-audit evidence. Apply it to an instance with a dry run first:

```bash theme={null}
airmux catalog apply --file taxonomy/taxonomy.yml --dry-run
airmux catalog apply --file taxonomy/taxonomy.yml
```

Catalog changes publish new bundles for affected organizations. They do not mutate requests already executing on an older snapshot.