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

# Provider routing

Sunra routes a canonical model ID to an available provider automatically. In most requests, omit `provider` and let Sunra select the route.

```json theme={null}
{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}
```

Use the optional `provider` object when you need a specific provider or want to control the eligible provider set. Provider routing is supported by Chat Completions, Messages, Responses, and Embeddings.

## Discover available providers

Provider availability varies by model and API format. Query the discovery endpoint before presenting provider choices in an application:

```bash theme={null}
curl "https://api-llm.sunra.ai/v1/models/google/gemini-2.5-flash/providers?format=chat%2Fcompletions" \
  -H "Authorization: Bearer <SUNRA_KEY>"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "google-vertexai",
      "name": "Google Vertex AI",
      "supported_formats": ["chat/completions", "messages", "responses"]
    },
    {
      "id": "openrouter",
      "name": "OpenRouter",
      "supported_formats": ["chat/completions", "messages", "responses"]
    }
  ]
}
```

The discovery endpoint uses the same API key authentication as the LLM inference endpoints. Supported `format` values are `chat/completions`, `messages`, `responses`, and `embeddings`.

## Select one provider

Set `provider.only` to restrict the request to one provider:

```bash theme={null}
curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "provider": {
      "only": ["google-vertexai"]
    },
    "messages": [
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'
```

The request returns an error when none of the requested providers can serve the model and API format.

## Set a preference order

Use `order` to prefer providers in sequence. Providers not listed in `order` remain eligible unless `allow_fallbacks` is `false`.

```json theme={null}
{
  "provider": {
    "order": ["google-vertexai", "openrouter"],
    "allow_fallbacks": false
  }
}
```

`allow_fallbacks` controls the initial eligible provider set. It does not retry a request through another provider after an upstream response or failure has started.

## Exclude providers

Use `ignore` to remove providers from automatic routing:

```json theme={null}
{
  "provider": {
    "ignore": ["openrouter"]
  }
}
```

## Prefer the lowest price

Use `sort: "price"` to prefer the lowest-priced eligible route. Price sorting applies when `order` is omitted.

```json theme={null}
{
  "provider": {
    "sort": "price"
  }
}
```

`latency` and `throughput` sorting are not currently supported.

## Provider fields

<ParamField body="provider" type="object">
  Optional routing preferences. Omit this object for automatic routing.

  <Expandable title="properties">
    <ParamField body="only" type="string[]">
      Restrict routing to these provider IDs.
    </ParamField>

    <ParamField body="order" type="string[]">
      Prefer providers in this order.
    </ParamField>

    <ParamField body="ignore" type="string[]">
      Exclude these providers from routing.
    </ParamField>

    <ParamField body="allow_fallbacks" type="boolean">
      When `order` is present, allow providers not listed in `order` to remain eligible. Defaults to `true`.
    </ParamField>

    <ParamField body="sort" type="string">
      Sort eligible providers. Currently supported value: `price`.
    </ParamField>
  </Expandable>
</ParamField>