> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Routing policies

> The three routing strategies (Priority, Intelligent, Build Your Own Router), how to select a policy with a model alias, how Gateway picks a vendor, and tag-based routing.

A routing policy picks the model and vendor for each request, so your code doesn't hard-code a model. Use one for cross-vendor failover, a cost or quality target, or model changes without a deploy.

## Select a policy with a model alias

Every organization-level policy gets a model alias from its name. Send the alias as `model` to route through that policy. This is the recommended approach: one API key reaches every policy, and policy edits reach every caller without a code change.

Set `model` to the policy's alias, such as `@alias/support-agent`.

Policies can also apply through a key binding, a project or customer default, or the organization default. See [Model aliases](/merge-gateway/routing/model-aliases) and [policy precedence](/merge-gateway/routing/using-policies#how-routing-policies-are-applied).

## Strategies

Create policies under [**Routing policies → Policies**](https://gateway.merge.dev/routing-policies) and set the organization default under [**Configure → Request settings → Defaults**](https://gateway.merge.dev/configuration/request-settings).

| Strategy                  | What it does                                                                                               | API `strategy`                                                   | Details                                                                     |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Priority**              | Tries models in your order, failing over to the next. One model is a valid list                            | `PRIORITY`                                                       | [Deterministic strategies](/merge-gateway/routing/deterministic-strategies) |
| **Intelligent**           | Scores each prompt's complexity and picks a model on the **Cost**, **Performance**, or **Capability** axis | `INTELLIGENT` with `axis` `COST`, `PERFORMANCE`, or `CAPABILITY` | [Intelligent routing](/merge-gateway/routing/intelligent)                   |
| **Build Your Own Router** | Picks the model with the highest weighted score across benchmarks you choose                               | Dashboard only                                                   | [Build Your Own Router](/merge-gateway/routing/build-your-own-router)       |

The [`/v1/routing-policies` API](/merge-gateway/management-api/routing-policies/create-routing-policy) creates Priority and Intelligent policies. Pick Priority for predictable, ordered failover, Intelligent to send easy prompts to cheaper models, and Build Your Own Router when you have evaluation data.

A policy chooses only among the models you add. The picker lists catalog models your organization's vendor, region, zero data retention, and credential settings allow. Intelligent also needs catalog capability metadata, so a model can appear for Priority but not Intelligent.

### Reasoning effort

Priority and Intelligent policies can set a default `reasoning.effort` for requests that omit it, plus minimum and maximum limits (Build Your Own Router can't). Per-model overrides set to **Inherit** use the policy value. Levels run `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, and each model accepts only the levels it supports.

## How Gateway picks a vendor

Vendor selection works the same whether a policy chose the model or you named it. Gateway starts from every active route for the model and drops routes that fail [zero data retention](/merge-gateway/security/zero-data-retention), your organization's vendor and region restrictions, or the request's required capabilities (such as tools or structured output). Routes that honor the requested `reasoning.effort` are preferred, not required. A `vendor` or `vendors` pin then picks from the survivors, so a pin can't bypass organization restrictions. Without a pin, your organization's vendor routing preference applies; otherwise **the cheapest route wins** on combined input and output price per million tokens at the current rate, with catalog priority breaking ties.

The model's direct provider, meaning the company that created it, gets no routing preference. For example, `deepseek/deepseek-v4-pro` can be served by another eligible vendor when that route is cheaper. Failover candidates follow the same order, with the cheapest capable route first. Pin a vendor when the route matters; the `x-merge-vendor` header (or `routing.vendor_used` with routing metadata on) shows which vendor served you.

## Tag-based routing

Tag rules send a request to a different strategy within a project policy. Send key-value pairs in the request's `tags` body field. A rule matches when every pair it lists appears on the request with the same value; extra request tags don't prevent a match. The first matching rule in list order wins. If no rule matches, the policy's default strategy applies. Configure rules on a project's **Routing** tab in [**Projects**](https://gateway.merge.dev/projects). Customer policies don't support tag rules.

## Next steps

#### [Model aliases](/merge-gateway/routing/model-aliases)

Select a policy by name in the model field

#### [Using routing policies](/merge-gateway/routing/using-policies)

Precedence, failover, and per-request priority lists

#### [Intelligent routing](/merge-gateway/routing/intelligent)

Route by prompt complexity on cost, performance, or capability