Routing policies API

The Routing policies API lets you manage your organization’s own routing policies over a management token, for infrastructure-as-code. Use it to create the org’s default policy (the one that applies when a request names no explicit policy and hits no project- or customer-scoped policy) and any standalone policies, from Pulumi or a script instead of the dashboard.

All requests go to https://api-gateway.merge.dev with Authorization: Bearer mgmt_<your_management_key> and require the manage_routing scope. Content-Type: application/json on any request with a body.

This surface manages org-level policies only. Project-scoped policies live on the Projects API (embedded in the project); per-customer policies live on the Embedded Routing Stack. A separate read-only GET /v1/routing/policies on the gateway-key API exists for runtime discovery; this API is the token-authed CRUD surface.

Strategies

A policy is PRIORITY (try priority_order in order, fall back on failure) or INTELLIGENT (pick per request from allowed_models). The two field sets are mutually exclusive by strategy. For INTELLIGENT, allowed_models is the authoritative pick-list; allowed_providers is optional and, if you send it, must match the providers of allowed_models (it does not filter independently), and it is returned derived from allowed_models on reads.

Create a policy

The org’s first policy becomes the default automatically; after that, pass is_default: true to make one the default.

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

List, get, update

Update is a full replacement of the strategy, applied in place: the policy id is stable across updates, so IaC diffs stay clean.

$
curl https://api-gateway.merge.dev/v1/routing-policies \
>
  -H "Authorization: Bearer mgmt_<your_management_key>"

Set the default

set-default makes one policy the org default and unsets the previous one in a single call.

$
curl -X POST https://api-gateway.merge.dev/v1/routing-policies/{policy_id}/set-default \
>
  -H "Authorization: Bearer mgmt_<your_management_key>"

Delete

Deleting the default leaves the org with no default until you set another; requests that named no policy then fall back to any per-request model pin.

$
curl -X DELETE https://api-gateway.merge.dev/v1/routing-policies/{policy_id} \
>
  -H "Authorization: Bearer mgmt_<your_management_key>"