Model aliases

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 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 page’s Model alias column shows it, including @alias/.

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."}
    ]
  }'

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

Any organization API key or management key can call /v1/routing-policies.

curl https://api-gateway.merge.dev/v1/routing-policies \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_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}
    ]
  }'

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

Errors

Next steps