AI Gateway Routing Rules

Routing rules let you control how AI Gateway handles your team's requests at the model level. You define team-wide rules that either rewrite a request from one model to another, or deny a model so requests for it are blocked. Rules apply to every request made with your team's AI Gateway credentials, so you can change routing behavior without editing application code.

Each rule has a type and matches requests by model:

• Rewrite: AI Gateway serves requests for the source model with a destination model instead. Use this to standardize on a model, roll out a replacement, or route an expensive model to a cheaper one.
• Deny: AI Gateway blocks requests for the matched model. Use this to stop your team from using a model you have not approved.

Each rule is scoped to a single team. You can attach an optional reason to a rule, which AI Gateway surfaces when the rule applies, and a description to document why the rule exists.

You manage routing rules with the vercel ai-gateway rules command. Target a team with the global --scope flag, or use your currently selected team. Every subcommand supports --format json for scripting.

vercel ai-gateway rules list --scope your-team

Create a rewrite rule with a source model (--source) and a destination model (--destination):

vercel ai-gateway rules add --type rewrite --source anthropic/claude-opus-5 --destination anthropic/claude-haiku-4.5

Once the rule is active, AI Gateway serves any request for anthropic/claude-opus-5 with anthropic/claude-haiku-4.5. Your application keeps requesting the source model and AI Gateway substitutes the destination.

Create a deny rule with the model to block:

vercel ai-gateway rules add --type deny --source openai/gpt-6-astra

A request for a denied model returns a 403:

{
  "error": {
    "message": "Request denied by a routing rule.",
    "param": { "ruleId": "rule_123" },
    "type": "forbidden"
  }
}

Update a rule by its ID. You can change the destination, reason, or description, or toggle the rule on and off:

vercel ai-gateway rules edit rule_123 --destination anthropic/claude-sonnet-5

vercel ai-gateway rules edit rule_123 --disable

A disabled rule stays in your configuration but stops applying to requests. To include disabled rules in the list, pass --include-disabled.

Delete a rule by its ID:

vercel ai-gateway rules remove rule_123

Routing rules apply to every request made with your team's AI Gateway credentials. Rule changes can take a short time to propagate. In-flight requests finish under the previous configuration, and new requests respect the updated rules once the change has propagated.

A deny rule also prevents the matched model from executing through a virtual model.

Rewrites apply before virtual model resolution, so a rewrite can send direct callers to a virtual model:

vercel ai-gateway rules add --type rewrite --source openai/gpt-6-astra --destination vmc/abc-123

The destination virtual model must be active: a missing or archived one is rejected with a 400. AI Gateway does not apply rewrites again to the model inside the virtual model, so rewriting a model to a virtual model that points back at it does not loop.

For example, if vmc/abc-123 points at openai/gpt-6-astra, that rewrite sends callers through the virtual model's configuration. A deny on openai/gpt-6-astra would also block its use through vmc/abc-123. Use the rewrite without the deny when you want callers to use the virtual model.

Each fallback selection goes through routing rules before AI Gateway tries it. Rewrites change the fallback destination. Deny rules prevent the matched fallback from executing, including when a virtual model resolves to it.

AI Gateway skips denied fallback candidates and can continue to another allowed model. If every candidate is denied, the request returns 403. If a deny matches the model you request directly, the request returns 403 immediately, even with fallbacks configured. A deny that matches only the model behind a requested virtual model skips that attempt and continues to the next fallback.

When an allowed model reaches a provider and fails, and every remaining candidate is denied, the request returns that failure. A candidate that never reaches a provider, for example when no provider matches its only filter, leaves the deny as the most specific result, so the request returns 403.

A fallback rewrite can itself point at a model that another rule rewrites. A chain that cycles back to an earlier model, or exceeds ten rewrites, is a configuration error. On the model you request, it fails the request with a 400. On a fallback, it skips that candidate the way a deny does, so an earlier failure or a later allowed candidate decides the response.

A rule only changes which model serves a request. Everything else you send is preserved and applied to the destination model, including providerOptions, the only filter, fallbacks, and BYOK.

One caveat: providerOptions are namespaced per provider and are not translated across providers. If a rewrite routes to a different provider, options for the original provider no longer apply (for example, providerOptions.anthropic has no effect on an openai destination). Keep rewrites within the same provider, or set the destination provider's options.

Routing rules are managed per team, so your access depends on your role in the team that owns the rules:

• Owners and Members can create, edit, and remove rules.
• Developers can view rules but not change them.
• Other roles have no access to routing rules.

• vercel ai-gateway rules CLI reference
• AI Gateway overview
• Provider allowlist