---
title: "Routes and aliases"
subtitle: "Give a list of models one name, tried in order or split by weight, and change it without a deploy."
---

A route is a model name your project defines in the platform, and the models it stands for. Your code sends the route's name as `model`; you change what it points to in one place. Routes are how you get fallbacks across models and load balancing between them. A route has one of two modes:

| Mode | Node | What a request does |
|---|---|---|
| `fallback` | Fallback | Tries the entries in order. The next entry runs only when the one before fails. |
| `split` | LoadBalance | Picks one entry by weight. If it fails, picks again from the rest. |

Create a route:

```bash
curl -X POST https://api.respan.ai/api/routes/ \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smart",
    "mode": "fallback",
    "entries": [{"name": "gpt-5.5"}, {"name": "claude-sonnet-4-5-20250929"}]
  }'
```

Then call it by name:

<Tabs>
<Tab title="cURL">
```bash
curl https://gateway.respan.ai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "smart", "messages": [{"role": "user", "content": "Hello!"}]}'
```
</Tab>
<Tab title="Python">
```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://gateway.respan.ai/v1", api_key=os.environ["RESPAN_API_KEY"])

response = client.chat.completions.create(
    model="smart",
    messages=[{"role": "user", "content": "Hello!"}],
)
```
</Tab>
<Tab title="TypeScript">
```typescript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://gateway.respan.ai/v1", apiKey: process.env.RESPAN_API_KEY });

const response = await client.chat.completions.create({
  model: "smart",
  messages: [{ role: "user", content: "Hello!" }],
});
```
</Tab>
</Tabs>

A request for `smart` tries every attempt of `gpt-5.5` (each offering on each key that can serve it, your own keys first), then every attempt of `claude-sonnet-4-5-20250929`.

## Route fields

| Field | Type | Default | Description |
|---|---|---|---|
| `name` | string | required | The name you send as `model`. Up to 255 characters; slashes are allowed. |
| `mode` | `"fallback"` or `"split"` | required | `fallback` tries entries in order and ignores weights. `split` picks an entry by weight, then picks again from the rest if it fails. |
| `entries` | object[] | required | At least one. |
| `entries[].name` | string | required | A model name (`gpt-5.5`), a provider offering (`azure/gpt-5.5`), a `<provider>/<model>` name, or a [Respan alias](#respan-aliases). |
| `entries[].weight` | number | `1` | Used by `split`. A split needs a positive total weight; an entry at 0 never runs. |

- A route with the same name as a catalog model replaces that model for your project.
- Every entry must name something your project can call; an unknown name is refused with `400`.
- If an entry stops resolving later, for example because a custom model was deleted, it's skipped. The route fails only when every entry does.
- Each model entry runs on your own provider keys first. Respan's keys serve an entry only when none of your keys can, or after your key answers `429` with [managed fallback](/docs/ai-gateway/routing/fallbacks#managed-fallback) on.

## Manage routes

Routes live on `https://api.respan.ai` and use your Respan API key.

| Method and path | What it does |
|---|---|
| `GET /api/routes/` | Lists your project's routes. |
| `POST /api/routes/` | Creates a route from `name`, `mode`, and `entries`. A name that already exists is refused with `409`. |
| `GET /api/routes/{name}/` | Returns one route. |
| `PATCH /api/routes/{name}/` | Updates `mode`, `entries`, or both. A field you leave out keeps its value; `entries` replaces the whole list. |
| `DELETE /api/routes/{name}/` | Deletes it. The name then resolves to a Respan alias or model of that name. |

Change a route's entries:

```bash
curl -X PATCH https://api.respan.ai/api/routes/smart/ \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries": [{"name": "claude-sonnet-4-5-20250929"}, {"name": "gpt-5.5"}]}'
```

With a dashboard session, only project admins can change routes.

{/* REVIEW: confirm whether routes get a page in the platform UI at launch, and how quickly a route change reaches gateway.respan.ai. */}

## Routes and providers

- To keep one entry on one provider, list its provider offering, such as `azure/gpt-5.5`, instead of the model name.
- The [`X-Respan-Route-Provider`](/docs/ai-gateway/routing/provider-routing#pin-a-provider) header on Messages, Responses, and Gemini narrows every entry to that provider. Entries the provider doesn't serve are skipped.
- For how a route nests with your keys' weights, see [Nest load balancing and fallback](/docs/ai-gateway/routing/load-balancing#nest-load-balancing-and-fallback).

## Respan aliases

Respan defines routes of its own, called aliases, that point to the current model of a family, such as `claude-sonnet-latest`. Send an alias as `model` like any model name. Your project's routes may list an alias as an entry; an alias lists models only, so routes never loop. A route of yours with the same name as an alias replaces it for your project.

An alias never moves a request off your own keys: your keys' attempts run first, whatever the alias's order or split, and Respan's keys follow only with managed fallback.

{/* REVIEW: confirm the list of Respan aliases at launch and what each points to; the alias mechanism exists, but no aliases are defined in the code. */}

## What you see and pay

The request's log shows the model, provider, and deployment that served it. You pay for the entry that answered: a call on Respan's key is charged to your credits from the provider's reported usage, and a call on your own key is billed by your provider. Earlier failed attempts are rows in the same trace.

## Next steps

- [Load balancing](/docs/ai-gateway/routing/load-balancing): split traffic across models or keys.
- [Fallbacks](/docs/ai-gateway/routing/fallbacks): how a failed entry moves to the next.
- [Provider routing](/docs/ai-gateway/routing/provider-routing): pin a provider and see how attempts are ordered.
- [Models and providers](/docs/ai-gateway/models/overview)