Skip to main content
When your application sends a raw model name like gpt-4o, the model is baked into your code. Change it and you ship a deploy. A named route breaks that coupling: your application calls a stable name, and the model behind it is configuration you change in the dashboard.

​
Before you start

Connect at least one provider with one or more models — see Connect a provider.

​
Create a named route

  1. Go to Project → AI Gateway → Routing and start a new routing rule.
  2. Give it a routing identifier — the stable name your application will call, such as summarize. Pick something that describes the task, not the model.
  3. Choose a strategy and the model behind it: a single model (Direct routing), a weighted split, a fallback chain, or an A/B experiment.
  4. Save the rule.

​
Call it by name

Set the request’s model to route::<name>: 
curl https://gw.to11.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-to11-authorization: Bearer $TO11_API_KEY" \
  -H "x-to11-project-id: $TO11_PROJECT_ID" \
  -d '{
    "model": "route::summarize",
    "messages": [{ "role": "user", "content": "Summarize this article..." }]
  }'
The gateway looks up the route by name and applies its strategy. To change which model serves summarize, edit the route in the dashboard — every caller using route::summarize follows the change with no code edit.
The route:: prefix sends the request straight to that route. A bare model name with no prefix is matched top-down — a route with that name first, then a connected provider’s model — so the explicit prefix keeps routing predictable.

​
Other endpoints

Routes aren’t limited to chat. A route is tied to an endpoint kind — chat, embeddings, audio speech, audio transcription, or image generation — so you can give an embedding route a stable name the same way: 
const embedding = await client.embeddings.create({
  model: "route::embed",
  input: "Search query text",
});
If you call a route from the wrong endpoint — sending an embeddings route to the chat endpoint — the gateway rejects the request.

​
Next steps

Routing overview

Managed vs passthrough routing and the full resolution flow.

A/B experiment

Split traffic across model variants and compare them.

Fallback chain

Automatic failover between providers.

Functions

Why model-agnostic routing matters.