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

# Tag Routing

> Route requests to backends with specific capabilities like vision, PDF input, or reasoning

# Tag Routing

*Guarantee the capabilities your request needs*

Not every backend supports every feature for a given model. Tag routing lets you declare exactly which capabilities your request requires — and AnyAPI guarantees it lands on a backend that supports them all. No more random failures because a backend can't handle your PDFs, audio, or tool calls.

```json theme={"system"}
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [{"role": "user", "content": "Summarize this document"}],
  "tags": ["messages:pdf_input"]
}
```

## How It Works

Add the `tags` parameter to your request with the capabilities you need. AnyAPI filters available backends to only those that match **all** your requested tags, then routes to the best one.

* **All tags must match** — if you send `["vision", "streaming"]`, the backend must support both
* **No match = 503** — if no backend supports all your tags, you'll get a clear error instead of a cryptic failure
* **Fully optional** — skip tags entirely and AnyAPI routes as usual

## 🏷️ Tag Format

Tags use a simple two-level naming scheme:

```
endpoint:capability    → scoped to a specific API endpoint
capability             → matches any endpoint
```

**Use endpoint-scoped tags when possible.** A capability might be available on one endpoint but not another — scoped tags give you precision.

### Endpoint Prefixes

| Prefix             | API Endpoint           |
| ------------------ | ---------------------- |
| `chat_completions` | `/v1/chat/completions` |
| `messages`         | `/v1/messages`         |
| `responses`        | `/v1/responses`        |

### Available Capabilities

| Tag                         | What it guarantees                                          |
| --------------------------- | ----------------------------------------------------------- |
| `vision`                    | Image input support                                         |
| `pdf_input`                 | PDF file input support                                      |
| `audio_input`               | Audio file input support                                    |
| `reasoning`                 | Extended thinking / chain-of-thought                        |
| `streaming`                 | Streaming response support                                  |
| `function_calling`          | Function / tool calling                                     |
| `parallel_function_calling` | Multiple tool calls in one turn                             |
| `tool_choice`               | Explicit tool selection (`auto`, `required`, `none`, named) |
| `computer_use`              | Computer use tool support                                   |
| `assistant_prefill`         | Pre-fill assistant response                                 |
| `prompt_caching`            | Prompt caching support                                      |
| `web_search`                | Built-in web search                                         |
| `url_context`               | URL context fetching                                        |

Every capability works as a generic tag (`vision`) and as an endpoint-scoped tag (`chat_completions:vision`, `messages:vision`, `responses:vision`).

## 📨 Sending Tags

### Request Body (recommended)

Pass a `tags` array alongside your usual parameters:

```json theme={"system"}
{
  "model": "anthropic/claude-sonnet-4",
  "messages": [{"role": "user", "content": "Describe this image"}],
  "tags": ["chat_completions:vision"]
}
```

### HTTP Header

Use the `x-router-tags` header with comma-separated values:

```bash theme={"system"}
curl https://api.anyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-router-tags: chat_completions:vision,streaming" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-4", "messages": [...]}'
```

> If both `tags` in the body and `x-router-tags` header are present, the body takes precedence.

## 🧪 Examples

### Vision — analyze an image

```bash theme={"system"}
curl https://api.anyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {"role": "user", "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]}
    ],
    "tags": ["chat_completions:vision"]
  }'
```

### PDF — summarize a document

```bash theme={"system"}
curl https://api.anyapi.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": [
        {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "..."}},
        {"type": "text", "text": "Summarize this document"}
      ]}
    ],
    "tags": ["messages:pdf_input"]
  }'
```

### Streaming + Tool Calling

```bash theme={"system"}
curl https://api.anyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [{"role": "user", "content": "What is the weather in Berlin?"}],
    "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
    "stream": true,
    "tags": ["chat_completions:function_calling", "chat_completions:streaming"]
  }'
```

### Reasoning via header

```bash theme={"system"}
curl https://api.anyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-router-tags: chat_completions:reasoning" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Solve step by step: what is 7! + 3!?"}]
  }'
```

## ⚠️ Error Handling

When no backend matches your tags, AnyAPI returns a **503** with a clear message:

```json theme={"system"}
{
  "error": {
    "message": "There is no available model deployment that meets your routing requirements",
    "type": "None",
    "code": "503"
  }
}
```

**Common causes:**

* The model doesn't support this capability on any backend
* Typo in a tag name — check the tag list above
* You're using a generic tag but the capability is only available on specific endpoints

## 🔍 Discovering Tags for a Model

Query which tags any model supports:

```bash theme={"system"}
curl https://api.anyapi.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" | \
  jq '.data[] | select(.id == "anthropic/claude-sonnet-4") | .tags'
```

This returns every tag available across all backends for the model. If a tag appears in the list, at least one backend supports it. Models with no capability tags omit the `tags` field.

## Tips

* **Start without tags** — only add them when you need a specific capability that isn't available everywhere
* **Use endpoint-scoped tags** — `chat_completions:vision` is safer than just `vision` because it guarantees the capability on the exact endpoint you're calling
* **Combine with fallback chains** — use the `models` parameter alongside tags for maximum reliability
* **Check before you build** — query `/v1/models` to see which tags your target model supports before hardcoding them