Routes and aliases

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:

Create a route:

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:

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

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!"}],
)

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!" }],
});

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

• 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 on.

Manage routes

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

Change a route’s entries:

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.

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 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.

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.

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: split traffic across models or keys.
• Fallbacks: how a failed entry moves to the next.
• Provider routing: pin a provider and see how attempts are ordered.
• Models and providers