superhighfives · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 23, 2026
@@ -369,6 +369,10 @@
 /ai-crawl-control/features/pay-per-crawl/use-pay-per-crawl-as-site-owner/monitor-metrics/ /ai-crawl-control/features/pay-per-crawl/use-pay-per-crawl-as-site-owner/monitor-activity/ 301
 
 # AI Gateway
+/ai-gateway/features/model-aliases/ /ai-gateway/features/routing/model-aliases/ 301
+/ai-gateway/features/dynamic-routing/ /ai-gateway/features/routing/dynamic-routing/ 301
+/ai-gateway/features/dynamic-routing/json-configuration/ /ai-gateway/features/routing/dynamic-routing/json-configuration/ 301
+/ai-gateway/features/dynamic-routing/usage/ /ai-gateway/features/routing/dynamic-routing/usage/ 301
 /ai-gateway/get-started/configuring-settings/ /ai-gateway/get-started/ 301
 /ai-gateway/get-started/connecting-applications/ /ai-gateway/get-started/ 301
 /ai-gateway/get-started/creating-gateway/ /ai-gateway/get-started/ 301

@@ -44,7 +44,7 @@ export default {
 
 With `createAI` you get:
 
-- **Every model by id.** Workers AI `@cf/` ids, any model in the [AI Gateway catalog](/ai/models/), and [dynamic routes](/ai-gateway/features/dynamic-routing/) as `dynamic/<route>`.
+- **Every model by id.** Workers AI `@cf/` ids, any model in the [AI Gateway catalog](/ai/models/), and [dynamic routes](/ai-gateway/features/routing/dynamic-routing/) as `dynamic/<route>`.
 - **Vendor model objects.** Pass a model from the vendor's own package, such as `ai(anthropic("claude-opus-5-5"))`. It goes unchanged to AI Gateway's [provider-native endpoint](/ai-gateway/usage/providers/).
 - **The binding, or an account id and API token.** Use a gateway in another account, or call from outside a Worker.
 - **Gateway options, fallback, and BYOK.** Caching, logging, metadata, retries, `byokAlias`, `zdr`, and `vendorKey`.

@@ -27,7 +27,7 @@ We've also combined the previously separate code example sections into one view
 
 **Dynamic Routing**
 
-- The [route builder](/ai-gateway/features/dynamic-routing/) is now more performant and responsive.
+- The [route builder](/ai-gateway/features/routing/dynamic-routing/) is now more performant and responsive.
 - You can now copy route names to your clipboard with a single click.
 - Code examples use the [Universal Endpoint](/ai-gateway/usage/universal/) format, making it easier to integrate routes into your application.
 

@@ -12,6 +12,6 @@ You can configure the retry count (up to 5 attempts), the delay between retries
 
 ![Retry Requests settings in the AI Gateway dashboard](~/assets/images/ai-gateway/auto-retry-changelog.png)
 
-This is particularly useful when you do not control the client making the request and cannot implement retry logic on the caller side. For more complex failover scenarios — such as failing across different providers — use [Dynamic Routing](/ai-gateway/features/dynamic-routing/).
+This is particularly useful when you do not control the client making the request and cannot implement retry logic on the caller side. For more complex failover scenarios — such as failing across different providers — use [Dynamic Routing](/ai-gateway/features/routing/dynamic-routing/).
 
 For more information, refer to [Manage gateways](/ai-gateway/configuration/manage-gateway/#retry-requests).
@@ -0,0 +1,24 @@
+---
+title: Model aliases in AI Gateway (Beta)
+description: Give models a stable name and update routing preferences in AI Gateway without changing application code.
+date: 2026-10-22
+---
+
+AI Gateway now supports model aliases in beta. An alias gives one or more models a stable name, such as `custom/support-fast`. You can update the models without changing your application code.
+
+Keep models in a preferred order for fallbacks. Or use smart routing to rank models by cost or quality. Create and manage aliases on your gateway's **Routing** page, alongside dynamic routes.
+
+To call an alias through the [REST API](/ai-gateway/usage/rest-api/), use its name as the `model`. For example, send this body to `/accounts/{account_id}/ai/run`:
+
+```json
+{
+	"model": "custom/support-fast",
+	"input": {
+		"messages": [{ "role": "user", "content": "Reply with a short greeting." }]
+	}
+}
+```
+
+Include the `cf-aig-gateway-id` header to select the gateway where you created the alias. Aliases are scoped to individual gateways.
+
+For setup instructions and routing options, refer to [Model aliases](/ai-gateway/features/routing/model-aliases/).
@@ -145,7 +145,7 @@ Unified Billing requires [authentication](/ai-gateway/configuration/authenticati
 
 ## Call a dynamic route
 
-An [AI Gateway dynamic route](/ai-gateway/features/dynamic-routing/) is named `dynamic/<route>`. The route you configured on the gateway picks the model, and can apply conditions, percentages, rate and budget limits, and its own fallbacks:
+An [AI Gateway dynamic route](/ai-gateway/features/routing/dynamic-routing/) is named `dynamic/<route>`. The route you configured on the gateway picks the model, and can apply conditions, percentages, rate and budget limits, and its own fallbacks:
 
 ```ts
 const ai = createAI({ binding: env.AI, id: "my-gateway" });
@@ -571,7 +571,7 @@ A string can be a Workers AI id, a catalog id, or a dynamic route.
 
 - [pi-ai provider](/agents/models/pi-ai/)
 - [Model catalog](/ai/models/)
-- [Dynamic routing](/ai-gateway/features/dynamic-routing/)
+- [Dynamic routes](/ai-gateway/features/routing/dynamic-routing/)
 - [AI Gateway provider-native endpoints](/ai-gateway/usage/providers/)
 - [AI Gateway Worker binding methods](/ai-gateway/usage/worker-binding-methods/)
 - [Unified Billing](/ai-gateway/features/unified-billing/)
@@ -41,7 +41,7 @@ ai(anthropic("claude-opus-5-5")); // the vendor's own model object
 
 - **A Workers AI model** is a `@cf/` id. It runs through `env.AI.run()`. A compatibility layer turns each model's response into the standard OpenAI chat completions shape.
 - **An AI Gateway catalog model** is an `<author>/<model>` id from the [model catalog](/ai/models/), such as `anthropic/claude-opus-5.5` or `openai/gpt-5.5`. It also runs through `env.AI.run()`, which sends it to AI Gateway. The gateway picks a provider and bills the call. Use the catalog's spelling, not the vendor's: `anthropic/claude-opus-5.5`, not `claude-opus-5-5`.
-- **A [dynamic route](/ai-gateway/features/dynamic-routing/)** is `dynamic/<route>`. The route you configured on the gateway picks the model.
+- **A [dynamic route](/ai-gateway/features/routing/dynamic-routing/)** is `dynamic/<route>`. The route you configured on the gateway picks the model.
 - **A model object** comes from the vendor's provider package, such as `anthropic("claude-opus-5-5")`. The vendor's code builds the request and parses the response. The provider sends that request unchanged through the binding to AI Gateway's [provider-native endpoint](/ai-gateway/usage/providers/) for that vendor.
 
 The providers do not use the deprecated [Universal Endpoint](/ai-gateway/usage/universal/).

@@ -123,7 +123,7 @@ ai(getBuiltinModel("anthropic", "claude-opus-5-5"));
 
 Any other string throws a `TypeError`. The provider does not guess what a prefix means.
 
-A [dynamic route](/ai-gateway/features/dynamic-routing/) runs on `env.AI.run()` under the gateway you created it on, so set that gateway's `id`. The route picks the model and answers in the chat completions format. It takes the same metadata defaults and overrides as a Workers AI id.
+A [dynamic route](/ai-gateway/features/routing/dynamic-routing/) runs on `env.AI.run()` under the gateway you created it on, so set that gateway's `id`. The route picks the model and answers in the chat completions format. It takes the same metadata defaults and overrides as a Workers AI id.
 
 A catalog id uses the AI Gateway catalog's spelling, `anthropic/claude-opus-5.5`. Pi AI's own list spells Claude ids the way Anthropic does (`claude-opus-5-5`), so the provider lists them under the catalog spelling. A model object from a vendor registry keeps the vendor's spelling.
 
@@ -264,5 +264,5 @@ const result = await ai.generateImages(images, {
 - [AI SDK provider](/agents/models/ai-sdk/)
 - [Pi harness](/agents/harnesses/pi/)
 - [Model catalog](/ai/models/)
-- [Dynamic routing](/ai-gateway/features/dynamic-routing/)
+- [Dynamic routes](/ai-gateway/features/routing/dynamic-routing/)
 - [Pi AI](https://github.com/earendil-works/pi/tree/main/packages/ai)
@@ -19,7 +19,7 @@ The keys are stored securely with [Secrets Store](/secrets-store/) and allows fo
 
 - Secure storage and limit exposure
 - Easier key rotation
-- Rate limit, budget limit and other restrictions with [Dynamic Routes](/ai-gateway/features/dynamic-routing/)
+- Rate limit, budget limit and other restrictions with [dynamic routes](/ai-gateway/features/routing/dynamic-routing/)
 
 ## Setting up BYOK
 

@@ -663,6 +663,6 @@ If you receive a 404 from the upstream provider, the most common cause is an inc
 - [Get started with AI Gateway](/ai-gateway/get-started/)
 - [Configure authentication](/ai-gateway/configuration/authentication/)
 - [BYOK (Store Keys)](/ai-gateway/configuration/bring-your-own-keys/)
-- [Dynamic routing](/ai-gateway/features/dynamic-routing/)
+- [Dynamic routes](/ai-gateway/features/routing/dynamic-routing/)
 - [Caching](/ai-gateway/features/caching/)
 - [Rate limiting](/ai-gateway/features/rate-limiting/)
@@ -89,7 +89,7 @@ To configure retry settings:
 
 These gateway-level defaults apply to all requests routed through the gateway. Per-request headers can override these defaults — refer to [Request handling](/ai-gateway/configuration/request-handling/#request-retries) for details.
 
-For more complex failover scenarios where you need to fail across different providers, refer to [Dynamic Routing](/ai-gateway/features/dynamic-routing/).
+For more complex failover scenarios where you need to fail across different providers, refer to [dynamic routes](/ai-gateway/features/routing/dynamic-routing/).
 
 ## Delete gateway
 

@@ -10,7 +10,7 @@ products:
 
 :::note
 
-[Dynamic Routing](/ai-gateway/features/dynamic-routing/) also offers timeouts and retries per model, along with conditional routing, rate limiting, and budget limiting through a visual interface. This page documents request-handling configuration available through per-request `cf-aig-*` headers that work with any provider endpoint. You can also configure retries at the [gateway level](/ai-gateway/configuration/manage-gateway/#retry-requests).
+[Dynamic routes](/ai-gateway/features/routing/dynamic-routing/) also offer timeouts and retries per model, along with conditional routing, rate limiting, and budget limiting through a visual interface. This page documents request-handling configuration available through per-request `cf-aig-*` headers that work with any provider endpoint. You can also configure retries at the [gateway level](/ai-gateway/configuration/manage-gateway/#retry-requests).
 
 :::
 

@@ -1,6 +1,6 @@
 ---
 title: Features
-description: Explore AI Gateway features including caching, rate limiting, guardrails, dynamic routing, and data loss prevention.
+description: Explore AI Gateway features including caching, rate limiting, guardrails, routing, and data loss prevention.
 pcx_content_type: overview
 order: 1
 sidebar:
@@ -69,17 +69,16 @@ Automatically route each request to the most cost-effective model that can handl
 
 </Feature>
 
-<Feature header="Dynamic Routing" href="/ai-gateway/features/dynamic-routing/" badge="Beta">
+<Feature header="Routing" href="/ai-gateway/features/routing/">
 
-Create sophisticated request routing flows without code changes. Route requests based on user segments, geography, content analysis, or A/B testing requirements through a visual interface.
+Choose models without changing application code. Use model aliases for shared model choices and routing preferences, or dynamic routes for conditional flows.
 
 **Key benefits:**
 
-- Visual flow-based configuration
-- User-based and geographic routing
-- A/B testing and fractional traffic splitting
-- Context-aware routing based on request content
-- Dynamic rate limiting with automatic fallbacks
+- Stable model names with configurable model order or smart routing
+- Conditional routing and percentage-based traffic splits
+- Rate and budget limits within dynamic routes
+- Fallbacks when a model is unavailable
 
 </Feature>
 
@@ -211,7 +210,7 @@ Override default pricing with your negotiated rates or custom cost models. Apply
 ## Getting Started with Features
 
 1. **Start with the basics**: Enable [Caching](/ai-gateway/features/caching/) and [Analytics](/ai-gateway/observability/analytics/) for immediate benefits
-2. **Add reliability**: Configure Fallbacks and Rate Limiting using [Dynamic routing](/ai-gateway/features/dynamic-routing/)
+2. **Add reliability**: Configure Fallbacks and Rate Limiting using [dynamic routes](/ai-gateway/features/routing/dynamic-routing/)
 3. **Enhance security**: Implement [Guardrails](/ai-gateway/features/guardrails/), [DLP](/ai-gateway/features/dlp/), and [Authentication](/ai-gateway/configuration/authentication/)
 
 ---

@@ -1,10 +1,10 @@
 ---
-title: Dynamic routing
+title: Dynamic routes
 description: Route AI Gateway requests based on conditions, quotas, and fallbacks using a visual interface or JSON configuration.
 pcx_content_type: navigation
 order: 1
 sidebar:
-  order: 6
+  order: 2
   group:
     badge: Beta
 products:
@@ -48,7 +48,7 @@ Ensure your gateway has [authentication](/ai-gateway/configuration/authenticatio
 :::
 
 1. Create a route.
-   - Go to **(Select your gateway)** > **Dynamic Routes** > **Add Route**, and name it (for example, `support`).
+   - Select your gateway, go to **Routing**, then select **Create dynamic route**. Name the route (for example, `support`).
    - Open **Editor**.
 2. Define conditionals, limits and other settings.
    - You can use [Custom Metadata](/ai-gateway/observability/custom-metadata/) in your conditionals.
@@ -60,7 +60,7 @@ Ensure your gateway has [authentication](/ai-gateway/configuration/authenticatio
    - Click **Save** to save the state. You can always roll back to earlier versions from **Versions**.
    - Deploy the version to make it live.
 5. Call the route from your code.
-   - Use the route name in place of the model, for example, `dynamic/support`. See [Using a dynamic route](/ai-gateway/features/dynamic-routing/usage/) for examples.
+   - Use the route name in place of the model, for example, `dynamic/support`. See [Using a dynamic route](/ai-gateway/features/routing/dynamic-routing/usage/) for examples.
 
 :::note
 

@@ -117,8 +117,7 @@ export default {
 
 ## Response Metadata
 
-The response from a dynamic route is the same as the response from a model. There is additional metadata used to notify the model and provider used, you can check the following headers 
+The response from a dynamic route is the same as the response from a model. There is additional metadata used to notify the model and provider used, you can check the following headers:
 
 - `cf-aig-model` - The model used
 - `cf-aig-provider` - The slug of provider used
-
@@ -0,0 +1,25 @@
+---
+title: Routing
+description: Choose how AI Gateway selects models with model aliases and dynamic routes, without changing application code.
+pcx_content_type: navigation
+sidebar:
+  order: 6
+products:
+  - ai-gateway
+---
+
+import { Feature } from "~/components";
+
+Routing lets you configure how AI Gateway selects models. In the dashboard, select your gateway, then go to **Routing** to manage model aliases and dynamic routes.
+
+<Feature header="Model aliases" href="/ai-gateway/features/routing/model-aliases/" badge="Beta">
+
+Give one or more models a stable name such as `custom/support-fast`. Use an alias to configure model order or smart routing preferences without updating your application.
+
+</Feature>
+
+<Feature header="Dynamic routes" href="/ai-gateway/features/routing/dynamic-routing/" badge="Beta">
+
+Build a routing flow with conditional branches, percentage splits, rate limits, and budget limits. Use a dynamic route when requests need to follow different paths based on rules you define.
+
+</Feature>
-Original file line number
+Diff line change
@@ Expand Up / @@ -10,7 +10,7 @@ products: @@
     :::note
-    [Dynamic Routing](/ai-gateway/features/dynamic-routing/) also offers timeouts and retries per model, along with conditional routing, rate limiting, and budget limiting through a visual interface. This page documents request-handling configuration available through per-request `cf-aig-*` headers that work with any provider endpoint. You can also configure retries at the [gateway level](/ai-gateway/configuration/manage-gateway/#retry-requests).
+    [Dynamic routes](/ai-gateway/features/routing/dynamic-routing/) also offer timeouts and retries per model, along with conditional routing, rate limiting, and budget limiting through a visual interface. This page documents request-handling configuration available through per-request `cf-aig-*` headers that work with any provider endpoint. You can also configure retries at the [gateway level](/ai-gateway/configuration/manage-gateway/#retry-requests).
     :::
@@ Expand Down @@