multi-router.aidocs

Routing

Alias

Stable names that point to a router and can be repointed to move every caller at once.

An alias is a second name for a router, such as production, that points to the router's id. Requests, API keys limited to specific routers, and Traffic can use the alias in place of the router's id, and repointing the alias to another router moves every caller to that router at once, with no change to applications or API keys. An alias is not a router type: it has no model, provider or settings of its own, and a request through an alias is served by the router it points to.

Alias names

An alias name is 1 to 120 characters of letters, digits, hyphens, underscores and periods, unique in the organization across router ids and aliases. The prefix rt_ is reserved for router ids. An alias can point to any router in the same organization except another alias, and a router can have several aliases.

Using an alias

A request names an alias the same way as a router id, in the model field as multi-router/production or production, or in the x-mr-router header. An API key limited to an alias follows the alias when it is repointed. In Traffic, the Alias column shows the alias the request used and the Router column shows the router that served it. A request through an alias returns router_disabled when either the alias or its router is disabled.

Managing aliases in the dashboard

Aliases are managed in the Aliases panel on each router's page, which lists the identifiers that resolve to the router. Add creates an alias: as the name is typed, the panel shows Available, or why the name cannot be used. Move to another router repoints an alias, and the panel notes that the mapping flips atomically and that requests in progress are unaffected; when API keys are limited to the alias, it also notes that those keys follow the alias to its new router. Remove alias deletes it.

Managing aliases with the API

Through the API, an alias is a label on a router, listed in the router's aliases field and managed with two endpoints that take the router's rt_ id:

MethodPathDescriptionScope
POST/v1/routers/{id}/aliasesAttach the alias sent as alias. Returns 201 for a new alias, or 200 when the alias is already on this router or moves here from another router.routers:write
DELETE/v1/routers/{id}/aliasesDetach the alias named in the alias query parameter.routers:delete
Create an aliasbash
curl -X POST https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ/aliases \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "production" }'
Repoint the aliasbash
curl -X POST https://api.multi-router.ai/v1/routers/rt_2Lw6Yd8NcV/aliases \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "production" }'

Attaching an alias to the router it should point to repoints it as a single atomic update, and the response names the previous router in moved_from. A router cannot be deleted while it has aliases; repoint or detach them first.

Detach the aliasbash
curl -X DELETE "https://api.multi-router.ai/v1/routers/rt_2Lw6Yd8NcV/aliases?alias=production" \
  -H "Authorization: Bearer $MR_API_KEY"

Errors

Creating, repointing and deleting aliases return the following errors:

ErrorStatusCause
invalid_alias400The name is invalid, or is a router id.
missing_field400The body has no alias.
unknown_field400The body has a field other than alias.
router_not_found404The router id matches no router in the organization.
policy_managed409The router was created by a tools policy.
alias_changed409The alias changed at the same time. Retry.
has_dependent_aliases409A router is deleted while it has aliases.
Gemini ProxyRouter Settings
Was this helpful?