Routing policies

Decide how a customer's requests pick a model

A customer routing policy picks the model when the customer’s request doesn’t pin one. PRIORITY is a ranked list that falls back to the next model on failure; INTELLIGENT lets Gateway choose per request from an allowed set, optimizing for COST, PERFORMANCE, or CAPABILITY.

Create a policy

POST /v1/customers/{customer_id}/routing-policies. The customer’s first policy becomes its default.

curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/routing-policies \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-a",
    "strategy": "PRIORITY",
    "priority_order": [
      { "model": "openai/gpt-5.5", "priority": 1 },
      { "model": "anthropic/claude-opus-4-8", "priority": 2 }
    ]
  }'

Naming a model the customer’s controls and key usage mode don’t allow returns 400, so check the customer’s allowed models first.

Change the default

Send is_default: true on create or PATCH, or call PUT /v1/customers/{customer_id}/default-routing-policy with {"routing_policy_id": "..."}. Deleting the default leaves the customer with none, so its requests fall back to your organization’s default policy.

GET, PATCH, and DELETE on /v1/customers/{customer_id}/routing-policies/{policy_id} manage a single policy.

Reference

Field	Type	Description
`id`	UUID	Pass as `routing_policy_id` to select this policy on a request
`name`, `description`	string	Label and optional description
`strategy`	enum	`PRIORITY` or `INTELLIGENT`. Custom strategies and tag rules aren’t supported on customer policies.
`is_default`	boolean	Used when a request names no policy
`priority_order`	list of `{model, priority}`	`PRIORITY` only. Models are tried in order.
`allowed_models`	list	Required for `INTELLIGENT`. The set Gateway chooses from.
`allowed_providers`	list	`INTELLIGENT` only. Derived from `allowed_models`. If you send it, it must match their providers.
`axis`	enum	`INTELLIGENT` only: `COST` (default), `PERFORMANCE`, or `CAPABILITY`
`created_at`, `modified_at`	datetime	Timestamps

Fields for the other strategy come back null; sending them, or duplicate models in a list, returns 422.

Next steps

Using routing policies

How policies resolve and how requests override them

Customer keys

Control which credentials serve the policy’s models