Model aliases

An alias is a named pointer to a concrete route: a (provider, model, region) triple from the model catalogue. You create alias big pointing at aws-bedrock/mistralai/ministral-3-3b-instruct/br-gru, then call the API with:

{
  "model": "alias/big",
  "messages": [{ "role": "user", "content": "Hello" }]
}

The gateway resolves big to its stored route at request time and routes exactly as if you had sent the full model ID. When you change your mind about which model “big” is, repoint the alias in the dashboard. Every client configured with alias/big picks up the new route on its very next request, so a coding agent or chat client only needs to be configured once.

Aliases are account-wide. Every API key on your account resolves the same aliases.

Creating and managing aliases

You can manage aliases in three places:

• The model catalogue. Every provider/region row on a model page has an Alias button that points an existing alias at that exact route or creates a new one from it.
• The Aliases page. List, create, rename, repoint, and delete, with a copyable alias/<name> for each. Each alias has a detail page with its usage stats and full change history.
• The API. Manage aliases programmatically with the same API key you call inference with (below).

Managing aliases via the API

All endpoints take your regular Authorization: Bearer <api key> and address aliases by name:

Create an alias and immediately use it:

curl -X POST https://api.lowrouter.ai/v1/aliases \
  -H "Authorization: Bearer $LOWROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "big", "provider": "aws-bedrock",
       "canonical_id": "mistralai/ministral-3-3b-instruct", "locode": "br-gru"}'

curl -X POST https://api.lowrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $LOWROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "alias/big", "messages": [{"role": "user", "content": "Hello"}]}'

Repointing takes the full target triple: send all of provider, canonical_id, and locode, not just the field you are changing.

Target shapes

provider, canonical_id and locode are flat top-level fields, as above. Two other shapes are also accepted, so a target copied straight out of a response works without reshaping:

# nested object
-d '{"name": "big", "target": {"provider": "aws-bedrock",
     "canonical_id": "mistralai/ministral-3-3b-instruct", "locode": "br-gru"}}'

# slash-joined string, the same form the `model` field uses
-d '{"name": "big", "target": "aws-bedrock/mistralai/ministral-3-3b-instruct/br-gru"}'

locode is optional in every shape and defaults to global. Where a flat field and a target value disagree, the flat field wins.

Auto targets

Set provider to auto to point the alias at auto/<creator>/<model> — LowRouter picks the provider and region at request time, honouring the key’s routing policy (order and gates), and fails over within the model’s own ladder exactly as a direct auto/ request would:

# flat fields
-d '{"name": "green", "provider": "auto", "canonical_id": "mistralai/mistral-large-2512"}'

# or the id as copied from the model page
-d '{"name": "green", "target": "auto/mistralai/mistral-large-2512"}'

An auto target takes no locode — auto routing chooses the region, so sending one is rejected with 422 invalid_alias_target on the locode field. The canonical model must be auto-routable (at least one enabled provider/region); an uncatalogued model is refused with the same 422.

An alias’s own fallback models work the same for an auto target as for a pinned one: they are walked after the auto ladder is exhausted.

Stats and history

Every request through an alias is attributed to it: the stats endpoint (and the alias detail page in the dashboard) breaks usage down by the model, provider, and region the alias resolved to at the time: request counts, prompt/completion/total tokens, plus cost and carbon totals.

Each breakdown row’s model is the canonical id: the same string you set as the target, sent in the request, and see in /v1/models. The rows therefore join directly against your own logs. The human-readable name, when the catalogue has one, is a separate display_name field.

Every create, rename, and repoint is recorded with its old and new values.

• Stats follow the alias, not its name: renaming keeps history and stats; deleting and recreating a name starts fresh.
• Attribution starts when this feature shipped. Earlier traffic is not retroactively assigned.

Alias names are 1–64 characters: lowercase letters, digits, - and _, starting with a letter or digit. Names are lowercased when created and when looked up, so alias/Big and alias/big are the same alias.

Each account can hold 5 aliases by default. The limit is visible on the aliases page; contact support if you need more.

Resolution semantics

• Two target kinds. A static target (a provider) pins one route: the request gets that exact provider/region or an error. An auto target delegates the pick to LowRouter under the key’s routing policy, with the same failover ladder a direct auto/ request gets. The target field shown by the API names the kind: the 4-part explicit form, or auto/<creator>/<model>.
• Billed like the target. An aliased request is billed at the resolved route’s per-region pricing, exactly what a request for that model ID would cost. The alias adds no fee.
• The response echoes the resolved model. model in the response carries the resolved full model ID, not the alias, so logs and downstream tooling always see what actually served the request. The alias you sent is echoed in lowrouter_metadata.requested_alias.
• Fail-closed. If an alias does not exist (or was deleted), the request fails with 404 alias_not_found. If an alias’s target can no longer be routed (the model left the catalogue or its region is unavailable), the request fails with the same error the explicit model ID would produce. The gateway never silently substitutes a different model, provider, or region.
• Deletes are immediate. Deleting an alias frees its name for reuse right away, and requests still using it get 404 alias_not_found. If live clients depend on an alias, repoint it instead of deleting it.

Errors

Aliases in the model list

GET /v1/models lists your aliases alongside the catalogue whenever the request carries your API key. Each alias/<name> entry is described by its target:

• provider, modality, capabilities, context_length and max_output_tokens are the target model’s own values.
• regions[] contains exactly the pinned target region: its four-segment ID, per-region pricing, and carbon figures. The target’s other regions never appear, because the pin is the alias.
• alias_target carries the concrete four-segment ID the alias currently points at, so tooling can join the entry against the rest of the listing.

GET /v1/models/alias/<name> describes a single alias the same way. An alias whose target can no longer be routed is omitted from the listing, and the detail endpoint answers with the same status and error code a completion request for that alias would get (see Errors). The list never advertises an ID that a completion request would refuse.

An unauthenticated GET /v1/models contains no alias entries: aliases are per-account, and there is no account to read them from.

Pick a region in Jan (or any fixed-list client)

Some OpenAI-compatible clients, such as Jan and Chatbox, only offer the models returned by GET /v1/models, with no free-form model input. Since aliases are listed there, a region-pinned alias is how you target a region from these clients:

1. Create an alias pinned to the region you want, e.g. eu-mistral → mistral/mistralai/mistral-large-2512/eu (the Aliases page, or POST /v1/aliases).
2. In the client, configure LowRouter as an OpenAI-compatible provider with your API key. The model picker now shows alias/eu-mistral.
3. Select it. Every request routes to the pinned region, and repointing the alias later re-routes the client without touching its configuration.

Worked scenario: repointing through a provider outage

Your coding agents all call alias/big, which points at mistral/mistralai/mistral-large-2512/eu. The provider has a bad afternoon and calls start failing with 503s. Instead of redeploying every client:

1. Pick a healthy substitute in the catalogue, for example the same model served by another provider.

2. Repoint the alias (the full triple, as always):

   BashCopy code

   curl -X PATCH https://api.lowrouter.ai/v1/aliases/big \
     -H "Authorization: Bearer $LOWROUTER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"provider": "scaleway",
          "canonical_id": "mistralai/mistral-medium-3.5-128b", "locode": "fr-par"}'

3. The very next alias/big request routes to the new target. When the outage ends, repoint back the same way.

Billing follows the target from the next request on. Responses before and after the repoint came from different routes, so you lose some reproducibility. Repointing is therefore a named, recorded action: GET /v1/aliases/big/history shows exactly when it happened, and every response’s model and lowrouter_metadata say who actually served it, so you keep an audit trail.

What aliases are not

• They are not a load-balancing mechanism. One alias points at exactly one route, and every request through it goes there while that route is healthy.
• They point at one route, but they can name what to try when it is unavailable. An alias carries its own fallback chain, and it overrides the chain on the key’s routing profile, since naming a route and naming what to do when it is down are one intent. See fallback models.
• They do not pin pricing. Repointing an alias changes what you are billed to the new target’s rate from the next request on.
• They are per-account, not per-key. There is no way to give two API keys different meanings for the same alias name.