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

# Project routing

> Attach a project-scoped routing policy with uses_organization_default_routing and routing_policy: ranked Priority or Intelligent strategies, replaced in place with a stable ID.

A project routes through your organization's default policy until you give it its own, for a workload that needs different models, failover, or cost trade-offs. The policy has the same shape as [Embedded Routing Stack policies](/merge-gateway/embedded-routing-stack/routing-policies).

## Reference

| Field                               | Meaning                                                                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `uses_organization_default_routing` | `true` (the default) routes through the org default and allows no `routing_policy`. `false` requires `routing_policy`                    |
| `routing_policy.strategy`           | `PRIORITY` tries `priority_order` in rank order and falls back on failure. `INTELLIGENT` picks per request from `allowed_models`         |
| `routing_policy.priority_order`     | `PRIORITY` only. A list of `{model, priority}`                                                                                           |
| `routing_policy.allowed_models`     | `INTELLIGENT` only. `allowed_providers` is derived from it and must match if you send it                                                 |
| `routing_policy.axis`               | `INTELLIGENT` only: `COST` (default), `PERFORMANCE`, or `CAPABILITY`, the dashboard's **Cost**, **Performance**, and **Capability** axes |
| `routing_policy.name`               | Optional. Defaults to "\<project name> routing policy" for a new policy. Omitted or `null` keeps the current name when replacing one     |
| `routing_policy.description`        | Optional. Omitted or `null` keeps the current description when replacing a policy. Send `""` to clear it                                 |

These are the dashboard's **Priority** and **Intelligent** strategies. [Build Your Own Router](/merge-gateway/routing/build-your-own-router) policies are dashboard only.

| Error | Cause                                                                                                         |
| ----- | ------------------------------------------------------------------------------------------------------------- |
| `422` | The routing fields contradict each other, a field is used with the wrong strategy, or a model is listed twice |
| `400` | A model is blocked by your organization's vendor restrictions or needs vendor access you don't have           |

## Create a project with its own routing

```bash
curl -X POST https://api-gateway.merge.dev/v1/projects \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Field Mappings",
    "uses_organization_default_routing": false,
    "routing_policy": {
      "strategy": "PRIORITY",
      "priority_order": [
        { "model": "openai/gpt-5.5", "priority": 1 },
        { "model": "anthropic/claude-opus-4-8", "priority": 2 }
      ]
    }
  }'
```

## Replace the policy

`routing_policy` on `PATCH` replaces the whole policy in place, keeping its `id` so infrastructure-as-code diffs stay clean. On a project using the org default, it creates one. Dashboard-only settings carry over: a custom classifier while the policy stays Intelligent, and reasoning settings for models still in it.

```bash
curl -X PATCH https://api-gateway.merge.dev/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $MERGE_GATEWAY_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_policy": {
      "strategy": "INTELLIGENT",
      "axis": "CAPABILITY",
      "allowed_models": ["openai/gpt-5.5", "anthropic/claude-opus-4-8"]
    }
  }'
```

To return to the org default, send `{"uses_organization_default_routing": true}`. That deletes the project's policy and returns `routing_policy: null`.

## Next steps

#### [Routing policies](/merge-gateway/routing/overview)

Compare strategies and choose one

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

See how a request's policy is resolved

#### [Projects API](/merge-gateway/automation/projects-api)

Manage the rest of a project's configuration