> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Model aliases

> Send @alias/<slug> as the model in any chat request to route through that routing policy. Covers how aliases are created, renamed, and managed from the dashboard or /v1/routing-policies, and the errors they return.

Every organization-level routing policy has a model alias, such as `@alias/support-agent`. Send it as `model` to route through that policy. It's the recommended way to select routing: one API key reaches every policy, and policy edits reach every caller with no deploy.

## How aliases are created

Creating a policy in the [dashboard](https://gateway.merge.dev/routing-policies) or through `/v1/routing-policies` mints an alias from its name: "Support agent" becomes `@alias/support-agent`. A policy created as the organization default gets `@alias/default`, and keeps it if the default later changes. Deleting a policy frees its alias. Project-scoped, customer-scoped, and inline policies get none. An organization can hold up to 200 aliases.

## Use an alias in a request

Send the alias exactly as the [Routing policies](https://gateway.merge.dev/routing-policies) page's **Model alias** column shows it, including `@alias/`.

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@alias/support-agent",
    "input": [
      {"type": "message", "role": "user", "content": "Summarize the attached incident report."}
    ]
  }'
```

**`Python`**

```python title="Python"
import os
from merge_gateway import MergeGateway

client = MergeGateway(api_key=os.environ["MERGE_GATEWAY_API_KEY"])

response = client.responses.create(
    model="@alias/support-agent",
    input=[{"type": "message", "role": "user", "content": "Summarize the attached incident report."}],
)
print(response.output[0].content[0].text)
```

**`OpenAI SDK`**

```python title="OpenAI SDK"
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MERGE_GATEWAY_API_KEY"],
    base_url="https://api-gateway.merge.dev/v1/openai",
)

completion = client.chat.completions.create(
    model="@alias/support-agent",
    messages=[{"role": "user", "content": "Summarize the attached incident report."}],
)
print(completion.choices[0].message.content)
```

Aliases work on `/v1/responses` and every compatible endpoint, so any coding agent or SDK that takes a model name can use one. The `x-merge-routing-policy-id` header names the serving policy, and logs record the alias and the served model. A key's `allowed_models` is checked against the model the policy selects. Compatible endpoints' model listings include your aliases; native `GET /v1/models` doesn't.

## Manage aliases with the API

Organization API keys can only read policies with [`/v1/routing-policies`](/merge-gateway/management-api/routing-policies/list-routing-policies). Creating, updating, deleting, and setting the default need a [management key](/merge-gateway/management-api) with `manage_routing`.

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/routing-policies \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support agent",
    "strategy": "PRIORITY",
    "priority_order": [
      {"model": "anthropic/claude-sonnet-5", "priority": 1},
      {"model": "openai/gpt-5.5", "priority": 2}
    ]
  }'
```

**`Python`**

```python title="Python"
import os
import requests

resp = requests.post(
    "https://api-gateway.merge.dev/v1/routing-policies",
    headers={"Authorization": f"Bearer {os.environ['MERGE_GATEWAY_MANAGEMENT_KEY']}"},
    json={
        "name": "Support agent",
        "strategy": "PRIORITY",
        "priority_order": [
            {"model": "anthropic/claude-sonnet-5", "priority": 1},
            {"model": "openai/gpt-5.5", "priority": 2},
        ],
    },
)
print(resp.json()["model"])  # "@alias/support-agent"
```

The response carries `"slug": "support-agent"` and `"model": "@alias/support-agent"`. Pass `slug` on create to choose the alias. Renaming a policy never changes its alias; edit the policy's **Model alias** field or `PATCH` a new `slug` instead, and callers sending the old alias get `404`.

## Reference

### Alias rules

| Rule                 | Detail                                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| Format               | 3 to 64 characters: lowercase letters, digits, `.`, `_`, `-`, starting and ending with a letter or digit |
| Normalization        | Uppercase is lowercased, and a leading `@alias/` is stripped                                             |
| Reserved             | `default_routing` and `fusion`                                                                           |
| Collisions on create | Suffixed automatically, such as `support-agent-2`, whether the name was derived or passed as `slug`      |
| Collisions on rename | `PATCH` with a taken `slug` returns `409`                                                                |
| Invalid alias        | `422`                                                                                                    |

### Errors

| Status and code                     | Cause                                                                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `404 model_not_found`               | Unknown alias, or its policy is deleted, inactive, or out of scope for the request                                                           |
| `503 model_resolution_unavailable`  | Transient failure resolving the alias. Safe to retry                                                                                         |
| `400 alias_routing_policy_conflict` | Alias sent with `routing_policy_id`                                                                                                          |
| `400 alias_not_supported`           | Alias sent to `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/videos`, `/v1/decisions`, or a live voice session. Send a model ID there |

## Next steps

#### [Routing policies](/merge-gateway/routing/overview)

Pick a strategy for the policy behind your alias

#### [Using routing policies](/merge-gateway/routing/using-policies)

How an alias fits into policy precedence

#### [Coding agents](/merge-gateway/coding-agents/overview)

Point Claude Code, Cursor, or Codex at Gateway