Project routing

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.

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

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.

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

Compare strategies and choose one

Using routing policies

See how a request’s policy is resolved

Projects API

Manage the rest of a project’s configuration