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

# Auto Routing

> Dynamically route requests to the best model.

Mesh API's Auto Router allows you to simply set `model: "auto"` on any inference request. The gateway will classify the request using an internal LLM and select the most appropriate model from the live registry, forwarding the request transparently.

This requires no client-side logic beyond setting the `model` field to `"auto"`.

## Supported endpoints

Auto Routing is supported across the following inference endpoints:

| Endpoint                    | Streaming Supported |
| --------------------------- | ------------------- |
| `POST /v1/chat/completions` | Yes                 |
| `POST /v1/responses`        | Yes                 |
| `POST /v1/embeddings`       | No                  |

## Basic request

Just replace your specific model ID with `"auto"`:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/chat/completions \
      -H "Authorization: Bearer <YOUR_RSK_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "auto",
        "messages": [{"role": "user", "content": "Write a Python quicksort implementation"}]
      }'
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```ts theme={null}
    const response = await client.chat.completions.create({
      model: "auto",
      messages: [{ role: "user", content: "Write a Python quicksort implementation" }],
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from meshapi import ChatMessage, ChatCompletionParams, MeshAPI

    client = MeshAPI(base_url="https://api.meshapi.ai", token="rsk_...")

    response = client.chat.completions.create(
        ChatCompletionParams(
            model="auto",
            messages=[ChatMessage(role="user", content="Write a Python quicksort implementation")],
        )
    )
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    params := meshapi.ChatCompletionParams{
        Model: meshapi.String("auto"),
        Messages: []meshapi.ChatMessage{
            {Role: "user", Content: meshapi.String("Write a Python quicksort implementation")},
        },
    }

    _, err := client.Chat.Completions.Create(ctx, params)
    ```
  </Tab>

  <Tab title="Java SDK">
    ```java theme={null}
    ChatCompletionRequest request = ChatCompletionRequest.builder()
        .model("auto")
        .addMessage(ChatMessage.user("Write a Python quicksort implementation"))
        .build();

    client.chat().completions().create(request);
    ```
  </Tab>
</Tabs>

## Response metadata

When a request is automatically routed, Mesh API injects metadata into the response so you know which model was actually used.

### Non-streaming requests

The metadata is included directly in the response body.

```json theme={null}
{
  "id": "chatcmpl-...",
  "model": "openai/gpt-4o",
  "choices": [...],
  "x_auto_routed": true,
  "x_resolved_model_id": "openai/gpt-4o"
}
```

If the internal classifier failed or timed out and a fallback model was used, additional fields are present:

```json theme={null}
{
  "x_auto_routed": true,
  "x_resolved_model_id": "openai/gpt-4o-mini",
  "x_auto_routed_fallback": true,
  "x_auto_routed_fallback_reason": "classifier_timeout"
}
```

### Streaming requests

For streaming requests (`stream: true`), the metadata is included as HTTP response headers before the SSE stream begins:

```text theme={null}
X-Auto-Routed: true
X-Resolved-Model-Id: openai/gpt-4o
```

## Fallback behavior

The Auto Router is designed to never block a request due to its own failure. If the internal classification model fails to respond in time or returns an unknown model, the gateway will automatically fall back to a reliable default model (e.g., `openai/gpt-4o-mini`).

## Billing

When using the Auto Router, you are billed for the tokens consumed by the *resolved* model that actually served the request, **as well as the tokens consumed by the internal classifier model**. Both will appear in your usage dashboard.

***

## When to use auto routing

* **Rapid prototyping** — skip the model selection decision early in development
* **Mixed-complexity workloads** — let the gateway route simple queries to cheap models and hard ones to frontier models
* **A/B testing** — observe which models get selected for your actual traffic