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

# Chat completions

> OpenAI-compatible chat completions with MESH routing extensions.

`POST /v1/chat/completions`

```bash theme={null}
curl https://api.meshrouter.app/v1/chat/completions \
  -H "Authorization: Bearer $MESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}],"stream":true}'
```

## MESH extensions

| Field             | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `models`          | Ordered fallback model list                                          |
| `route`           | `auto` or `fallback`                                                 |
| `privacy`         | Privacy-class envelope (see below and [MESH privacy](/privacy/mesh)) |
| `response_format` | `text`, `json_object`, or `json_schema`                              |
| `tools`           | OpenAI-compatible function definitions                               |
| `tool_choice`     | `auto`, `none`, or a named function                                  |

Text, image, and tool messages use the OpenAI-compatible `messages` shape.

## Privacy envelope

```json theme={null}
{
  "privacy": {
    "class": "protected_provider_route",
    "bestAvailable": false,
    "allowFallbackToLowerClass": false
  }
}
```

| Field                        | Type    | Description                                                                                                             |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `class`                      | string  | One of `standard_route`, `protected_provider_route`, `private_gateway_route`, `confidential_runtime_route`. Optional.   |
| `bestAvailable`              | boolean | Ask MESH to pick the strongest class the selected model supports. Mutually preferred over an explicit `class`.          |
| `allowFallbackToLowerClass`  | boolean | If `class` is set and the model can't earn it, accept the strongest class it CAN earn instead of returning HTTP 422.    |
| `mode` *(legacy)*            | string  | `"standard"` → `standard_route`. `"mesh"` → `private_gateway_route`. Continues to work; new code should prefer `class`. |
| `encryptedPrompt` *(legacy)* | string  | Sealed-prompt envelope for legacy private callers. New code uses `class` instead.                                       |

## Response privacy block

Every billable chat completion response includes a `privacy` block:

```json theme={null}
{
  "model": "mesh/claude-sonnet-4.6",
  "privacy": {
    "class": "protected_provider_route",
    "label": "Protected",
    "mesh_stores_prompts": false,
    "mesh_logs_prompts": false,
    "training_on_prompts": false,
    "upstream_disclosed": false,
    "guarantee": "Uses stricter upstream data-protection requirements. MESH does not store prompts by default and training on prompts is not allowed."
  },
  "usage": { "...": "..." }
}
```

`upstream_disclosed` is always `false` — MESH never tells API consumers which upstream provider
served the call. The class is the durable guarantee.

## Response headers

| Header                     | Description                        |
| -------------------------- | ---------------------------------- |
| `x-mesh-upstream-cost-usd` | Model cost for this call           |
| `x-mesh-margin-usd`        | MESH margin                        |
| `x-mesh-total-usd`         | Total USD drawn from your balance  |
| `x-mesh-receipt-id`        | Receipt ID for `/v1/receipts/{id}` |

## Errors

| Status | Code                                  | Meaning                                                                                                             |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 422    | `privacy_class_unavailable_for_model` | Requested class is not earnable by the selected model. Set `allowFallbackToLowerClass: true` or pick another model. |
| 503    | `privacy_class_runtime_unavailable`   | Requested class is in-policy for the model but the runtime (Nitro / attestation) is not currently wired.            |
| 503    | `margin_floor_violated`               | Selected route is below the configured margin floor for the served class.                                           |