Skip to main content
When your application sends a model like openai::gpt-4o, the provider and model are 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 — 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 Name — the stable name your application will call, such as summarize. The drawer shows the slug it is saved as; that slug is what follows route::. 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>:
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 is the only way to reach a route. A bare name such as summarize is never matched against your routes: without a prefix, the gateway expects the x-to11-provider-id header and otherwise rejects the request with 400. function::summarize reaches the same route.

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