> ## 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.

# Model routing and failover

> Route catalog model IDs across provider families, select healthy credentials, and define bounded fallback plans.

Every inference request names one catalog model. `airmux` resolves that model to a provider profile, validates the
request, chooses a credential, and translates the request into the provider's wire format.

## Model IDs

Catalog IDs use `provider/model` form in managed deployments, for example `openai/gpt-4o-mini` or
`anthropic/claude-sonnet-4-6`. The prefix selects the provider entry; the catalog maps the public ID to the upstream
model name.

```bash theme={null}
airmux models list
airmux providers list
```

Each model declares:

* Input and output prices per million tokens
* Context window and maximum output tokens
* Input and output modalities
* Capabilities such as streaming, tools, reasoning, and structured output
* Parameter support where the provider or model has a known restriction

`airmux` checks capabilities and modalities before it resolves a provider credential.

## Credential selection

Eligible credentials are considered by scope, then priority:

1. Workspace credentials
2. Organization credentials
3. Instance credentials

`airmux` uses the first populated scope allowed by policy. Within that scope, lower numeric priority is tried first and
name breaks ties. It does not fall through to a broader scope when the selected scope has credentials but they fail.

Authentication failures and rate limits may advance to the next credential in the same scope. A rate-limited credential
enters a short cooldown so concurrent requests do not immediately reuse it.

## Parameter reconciliation

Provider profiles define aliases, accepted extra fields, and model-specific parameter support. Before the upstream call, `airmux` may:

* Re-spell a parameter for the provider
* Default an omitted `max_output_tokens` from policy or model metadata
* Clamp an explicit `max_output_tokens` to the model's catalog maximum
* Drop an unsupported optional parameter
* Forward a documented top-level extra field

Every default, clamp, emulation, or drop appears in `gateway.adjustments`. Use `strict_parameters` policy to reject a route that
would drop a supplied parameter.

## Fallback plans

A fallback rule names up to four backup model IDs and the failure classes that trigger them: `rate_limited`,
`upstream_unavailable`, and `timeout`. Its deadline covers secret resolution and every attempt until response headers
arrive; it does not cap the duration of an established stream. See
[model fallbacks](/docs/policies#model-fallbacks) for the rule shape and limits.

Every backup route is evaluated against the same workspace restrictions. A fallback cannot escape an allowlist, price
ceiling, credential rule, capability check, or parameter policy. Its effective output limit is recalculated from that
backup model's catalog ceiling.

<Info>
  Fallback is not exactly-once generation. A timed-out provider may continue work after `airmux` starts another attempt,
  and each attempt gets its own usage record.
</Info>

Configure failover in [workspace policies](/docs/policies#model-fallbacks).