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

# Canonical model

> See how caller dialects and provider families cross one typed request and response model.

`airmux` uses a canonical model as the shared format between callers and providers. Each ingress dialect translates into canonical
once; each provider family translates out once.

```mermaid theme={null}
flowchart LR
  O[Chat Completions] --> C[Canonical]
  R[Responses] --> C
  A[Messages] --> C
  C --> E1[OpenAI-compatible provider]
  C --> E2[Responses provider]
  C --> E3[Anthropic provider]
```

With `N` caller dialects and `M` provider families, this requires `N + M` translators. Routing, policies, capability
checks, parameter reconciliation, streaming accounting, and usage measurement operate on canonical values once.

## Typed content

Canonical messages have `system`, `user`, or `assistant` roles. Their typed parts include:

| Part          | Purpose                                                    |
| ------------- | ---------------------------------------------------------- |
| `text`        | Text input or output                                       |
| `image`       | URL or base64 image input                                  |
| `document`    | URL, base64 data, or provider file ID                      |
| `reasoning`   | Reasoning text plus optional opaque identity and signature |
| `tool_call`   | Tool name, call ID, and JSON argument text                 |
| `tool_result` | Result associated with a prior call ID                     |

Nested shapes are closed and reject unknown fields. The canonical request top level is open so
provider-specific parameters can travel to a compatible provider profile.

## Public protocol paths

The endpoint path selects the caller protocol:

* `/inf/v1/chat/completions` uses OpenAI Chat Completions
* `/inf/v1/responses` uses OpenAI Responses
* `/inf/v1/messages` uses Anthropic Messages

Headers and request-body fields cannot change the response protocol. The canonical model is an implementation boundary,
not a public HTTP surface.

## Visible translation

Translation loss is never silent. The response `gateway.adjustments` array names any parameter that was clamped,
emulated, or dropped and explains why. A strict-parameter policy can turn a would-be drop into a denial.

The selected ingress adapter also owns the response and error shape. A Messages caller receives Messages events and
errors even when `airmux` routed the request to a different provider family.