Model aliases

Every Routing Config has a model alias, a virtual model name like @alias/fast-experiment. Send it as the model in any Gateway request and the request routes through that config, intelligent routing and fallbacks included. Switching between routing setups is a one-word change in the request body: one organization API key, no per-config projects or keys.

The alias and the config are one thing: creating a config mints the alias, deleting the config removes it. Manage them on the Routing policies page or through the /v1/routing-policies API.

How it works

An alias separates what an application is configured to call from how that call is routed. The alias is the stable name; the config behind it is routing you can change at any time.

1. Creating a Routing Config mints its alias from the name: “Fast experiment” gets @alias/fast-experiment, and the organization default gets @alias/default
2. Requests set model to the alias, always prefixed with @alias/
3. Gateway resolves the alias for your organization and routes through that config
4. Editing the config changes routing for all traffic immediately, with no application change

Use an alias in a request

Send the alias exactly as shown on the Routing policies page, including the @alias/ prefix. It works on /v1/responses and on the OpenAI- and Anthropic-compatible endpoints.

$
curl -X POST https://api-gateway.merge.dev/v1/responses \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
>
  -d '{
>
    "model": "@alias/fast-experiment",
>
    "input": [
>
      {"type": "message", "role": "user", "content": "Summarize the attached incident report"}
>
    ]
>
  }'

1
from openai import OpenAI
2
3
client = OpenAI(
4
    base_url="https://api-gateway.merge.dev/v1/openai",
5
    api_key="YOUR_GATEWAY_API_KEY",
6
)
7
8
response = client.chat.completions.create(
9
    model="@alias/fast-experiment",
10
    messages=[{"role": "user", "content": "Summarize the attached incident report"}],
11
)

The response’s x-merge-routing-policy-id header carries the Routing Config that served the request, so you can confirm which config handled it when comparing several. Request logs keep the alias as the requested model and record the actually served model separately, so you can group usage by alias while still seeing what executed.

Manage configs and aliases from the API

The same org API key that sends requests can manage Routing Configs via /v1/routing-policies (management keys work too). Create a config and its alias comes back ready to use:

$
curl -X POST https://api-gateway.merge.dev/v1/routing-policies \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
>
  -d '{
>
    "name": "Fast experiment",
>
    "strategy": "PRIORITY",
>
    "priority_order": [
>
      {"model": "anthropic/claude-haiku-4-5", "priority": 1},
>
      {"model": "anthropic/claude-sonnet-4-5", "priority": 2}
>
    ]
>
  }'

The response includes "slug": "fast-experiment" and "model": "@alias/fast-experiment". Pass an explicit slug on create to pick the alias yourself, or PATCH with slug later to rename it.

Rules worth knowing

• Renaming a config never changes its alias. The alias is embedded in application config, so a rename must not break it. Edit the alias explicitly (from the config’s strategy tab, or PATCH with slug) when you want a new one; anything still sending the old alias gets 404s.
• Two configs never share an alias. A second config named “Fast experiment” gets @alias/fast-experiment-2; an explicitly chosen alias that is already taken returns a 409.
• Aliases are lowercase slugs. 3 to 64 characters, letters, digits, ., _ and -. The @alias/ prefix is reserved and added for you.
• Deleting a config deletes its alias, freeing the name for reuse.
• Send an alias or a routing_policy_id, not both. An alias already carries the routing decision, so a request that sets both is rejected with a 400 rather than Gateway guessing which one wins.
• Key allowlists apply to the model the config selects. If an API key restricts allowed_models, Gateway checks the model the config routes to, not the alias string.
• An unknown alias returns a 404 with code model_not_found, the same as an unknown model id. A transient failure while resolving an alias returns a retryable 503 with code model_resolution_unavailable, never a misleading 404.

Use an alias in coding tools

Because an alias is a valid model name, it drops into any tool that lets you set the model:

• Claude Code: set ANTHROPIC_BASE_URL to your Gateway’s Anthropic-compatible endpoint and ANTHROPIC_MODEL=@alias/fast-experiment. Gateway also advertises your aliases in its model listing, so they appear in the model picker.
• Codex CLI: point the provider at Gateway’s Responses endpoint and set the model to @alias/fast-experiment.
• opencode: opencode addresses models as provider/model and splits on the first slash, so configure the model as <your-gateway-provider>/@alias/fast-experiment.

GET /v1/models (and the OpenAI- and Anthropic-compatible listings) include your organization’s aliases alongside the catalog, so SDK model pickers and validation that read the listing accept them.

Next steps