Skip to navigation

Create Routing Policy

Create an organization routing policy. Clients use it by sending its model (@alias/<slug>) as the model. The organization’s first policy becomes the default automatically; otherwise send is_default true to make it the default. Needs a management key.

Authentication

AuthorizationBearer

A management key (mgmt_...), sent as Authorization: Bearer <key>. Reading /v1/routing-policies also accepts the organization’s gateway API keys; writing there needs a management key.

Request

This endpoint expects an object.
namestringRequired<=255 characters
The policy's name.
strategyenumRequired

PRIORITY tries priority_order in turn; INTELLIGENT picks among allowed_models per request, optimizing for axis.

Allowed values:
allowed_modelslist of strings or nullOptional
INTELLIGENT only. Kept in the order sent. A model listed twice is a 422. Models with no capability tier are dropped, so the response can list fewer.
allowed_providerslist of strings or nullOptional

INTELLIGENT only, optional. Not stored: responses rebuild it from allowed_models. If sent non-empty, it must name the same providers as allowed_models (order and repeats don’t matter), or the request fails with 422.

axisenum or nullOptional

INTELLIGENT only. What the router optimizes for: COST, PERFORMANCE or CAPABILITY. Omitted or null means COST.

Allowed values:
claude_only_for_harnessesboolean or nullOptional
Use only Claude models for this policy's requests from Claude Code, Claude Desktop and the Claude Agent SDK. Omitted or null means off.
complexity_classifier_idstring or nullOptionalformat: "uuid"

The id of a classifier from /v1/classifiers. An INTELLIGENT policy then judges how complex each request is with your classifier instead of the built-in scorer. An unknown classifier, or one without 3 examples on each side, is a 400. INTELLIGENT only.

cost_speed_presetenum or nullOptional

INTELLIGENT only. How the router trades cost for speed: SAVE_COST picks the cheapest model likely to succeed, BALANCED pays more when the time saved justifies it, PREFER_SPEED favors faster models at higher cost. Omitted or null means SAVE_COST. BALANCED and PREFER_SPEED need cost and speed presets enabled for the organization.

Allowed values:
descriptionstring or nullOptional
What the policy is for.
is_defaultboolean or nullOptional
Make this the organization's default policy, unsetting the previous one. The organization's first policy becomes the default either way.
priority_orderlist of objects or nullOptional

PRIORITY only. The priority values are kept as sent; responses list the entries sorted by priority. A model listed twice is a 422.

slugstring or nullOptional<=100 characters

The policy’s model alias, as a lowercase bare name. Omitted: derived from the name, or “default” when the policy becomes the organization default. A taken alias gets a suffix (“fast”, “fast-2”).

vendor_priorityobject or nullOptional

Vendor tiers for this policy’s requests, replacing the organization’s. Same shape and rules as the organization’s vendor_priority. Omitted or null means none.

Response

The created routing policy
allowed_modelslist of strings or null
INTELLIGENT only. In the order they were sent.
allowed_providerslist of strings or nullRead-only

INTELLIGENT only. The providers of allowed_models, sorted. Always rebuilt from allowed_models; never stored.

axisenum or null

INTELLIGENT only, else null. What the router optimizes for: COST, PERFORMANCE or CAPABILITY.

Allowed values:
created_atdatetimeRead-only
When the policy was created.
descriptionstring or null
What the policy is for.
idstringRead-only
The policy's id. It stays the same across updates.
is_defaultboolean
Whether this is the organization's default policy.
modelstring or nullRead-only

The ready-to-send model string for this policy, like “@alias/fast-experiment”. Send it as the model in any gateway request to route with this policy.

modified_atdatetimeRead-only
When the policy last changed.
namestring
The policy's name.
priority_orderlist of objects or null
PRIORITY only. Sorted by priority.
slugstring or null

The policy’s model alias as a bare name, like “fast-experiment”. Null only when no alias could be made, such as an organization at its alias limit.

strategyenum

PRIORITY tries priority_order in turn; INTELLIGENT picks among allowed_models per request, optimizing for axis.

Allowed values:
claude_only_for_harnessesbooleanOptionalDefaults to false
Whether this policy's requests from Claude Code, Claude Desktop and the Claude Agent SDK use only Claude models.
complexity_classifier_idstring or nullOptionalformat: "uuid"

The id of a classifier from /v1/classifiers. An INTELLIGENT policy then judges how complex each request is with your classifier instead of the built-in scorer. An unknown classifier, or one without 3 examples on each side, is a 400. null when the policy uses the built-in scorer.

cost_speed_presetenumOptionalDefaults to SAVE_COST

INTELLIGENT only. How the router trades cost for speed: SAVE_COST, BALANCED or PREFER_SPEED.

Allowed values:
vendor_priorityobject or nullOptional
The policy's vendor tiers, which replace the organization's for its requests. null when the policy has none.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
502
Bad Gateway Error
503
Service Unavailable Error