> ## Documentation Index
> Fetch the complete documentation index at: https://spillway.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing & aliases

> Rewrite a model to a cheaper equivalent, or fall back to one when it fails.

Routing runs after guardrails and the budget check, right before dispatch. It decides which
concrete provider/model a request actually goes to.

## Routing rules

A routing rule matches a request the same way a guardrail policy does (`virtual_key_ids`,
`team_ids`, `models`, `metadata`) and applies an action. Rules are evaluated in `priority`
order.

```jsonc theme={null}
// POST /api/routing-rules
{
  "priority": 10,
  "description": "route gpt-4.1 requests from the batch team to the mini tier",
  "match": {
    "team_ids": ["<batch-team-uuid>"],
    "models": ["gpt-4.1"]
  },
  "action": {
    "type": "rewrite_model",
    "to": { "provider": "openai", "model": "gpt-4.1-mini" },
    "fallbacks": [
      { "provider": "openai", "model": "gpt-4.1" }
    ]
  }
}
```

`action.to` is where the request actually goes. `action.fallbacks` is an ordered chain
tried if the primary target fails — a rewrite and a fallback chain in one rule, so a
cost-optimization rewrite doesn't have to sacrifice reliability.

## Aliases

An alias is a named target you can point multiple keys or rules at, so you can repoint
"the model we use for X" in one place instead of editing every consumer.

```jsonc theme={null}
// POST /api/aliases
{
  "alias": "fast-tier",
  "targets": [
    { "provider": "openai", "model": "gpt-4.1-mini" }
  ]
}
```

`targets` also accepts a weighted/keyed shape (`{ "default": [...] }`) for more complex
fallback sets — the same shape a budget's `fallbackAlias` (see [Budgets](https://spillway.mintlify.site/configuration/budgets.md))
resolves against when a budget's `onExceed` is `fallback`.

> [!NOTE]
>
> Both routing-rule targets and provider keys are currently scoped to the `openai` provider
> value in the schema — this is the CRUD surface for *selecting* a provider/model pair, not
> a statement about which wire dialects the gateway accepts. The data plane itself parses
> and speaks OpenAI, Anthropic, and Gemini request/response shapes; see
> [Architecture](https://spillway.mintlify.site/architecture.md#providers).

## Where next

> **[Budgets](https://spillway.mintlify.site/configuration/budgets.md)**
>
> `onExceed: "fallback"` resolves against an alias, not a raw model string.

> **[Architecture](https://spillway.mintlify.site/architecture.md)**
>
> Where routing sits in the request lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.