Create Routing Rule

Create Routing Rule

Create a new routing rule for the authenticated user.

Paid Plans Only

This endpoint requires a paid plan. Free plan users will receive a 403 Forbidden error.

Endpoint

POST /v1/routing-rules

Request Body

Parameter	Type	Required	Description
name	string	Yes	Human-readable name for the rule (max 128 characters)
is_enabled	boolean	Yes	Whether the rule is active
priority	integer	Yes	Priority for rule evaluation (-1000 to 1000, higher = first)
match_json	object|string	Yes	Conditions that trigger the rule
action_json	object|string	Yes	Actions to apply when rule matches

Match Conditions (match_json)

Condition	Type	Description	Example
contains	string or array	Text in input (case-insensitive)	"code" or ["code", "bug"]
metadata_equals	object	Metadata key-value pairs	{"task": "analysis"}
mode	string	Routing mode equals	"balanced", "cost", "quality", "latency"
task	string	Shorthand for metadata_equals.task	"coding"

Empty conditions ({}) match all requests.

Actions (action_json)

Action	Type	Description	Valid Values
set_provider	string	Force specific provider	openai, anthropic, gemini, mistral, deepseek
set_model	string	Force specific model	Any valid model name
set_mode	string	Override routing mode	balance, cost, quality, latency
add_warning	object	Add warning message	{"message": "text"}

Examples

Example 1: Force OpenAI for Coding Tasks

TypeScript

const rule = await client.routingRules.create({
  name: 'Coding Tasks → OpenAI',
  priority: 100,
  is_enabled: true,
  match_json: {
    task: 'coding'
  },
  action_json: {
    set_provider: 'openai',
    set_model: 'gpt-4o'
  }
});

console.log(rule.data.id); // Created rule ID

Python

rule = client.routing_rules.create(
    name="Coding Tasks → OpenAI",
    priority=100,
    is_enabled=True,
    match_json={"task": "coding"},
    action_json={
        "set_provider": "openai",
        "set_model": "gpt-4o"
    }
)

print(rule.data.id)  # Created rule ID

cURL

curl -X POST https://api.tokenrouter.io/v1/routing-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Coding Tasks → OpenAI",
    "priority": 100,
    "is_enabled": true,
    "match_json": {"task": "coding"},
    "action_json": {
      "set_provider": "openai",
      "set_model": "gpt-4o"
    }
  }'

Example 2: Cost Mode for Documentation

TypeScript

const rule = await client.routingRules.create({
  name: 'Documentation → Cost Mode',
  priority: 50,
  is_enabled: true,
  match_json: {
    contains: ['documentation', 'docs', 'readme']
  },
  action_json: {
    set_mode: 'cost'
  }
});

Python

rule = client.routing_rules.create(
    name="Documentation → Cost Mode",
    priority=50,
    is_enabled=True,
    match_json={"contains": ["documentation", "docs", "readme"]},
    action_json={"set_mode": "cost"}
)

cURL

curl -X POST https://api.tokenrouter.io/v1/routing-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Documentation → Cost Mode",
    "priority": 50,
    "is_enabled": true,
    "match_json": {"contains": ["documentation", "docs", "readme"]},
    "action_json": {"set_mode": "cost"}
  }'

Example 3: Default Rule with Warning

TypeScript

const rule = await client.routingRules.create({
  name: 'Always Warn About Beta',
  priority: -100,
  is_enabled: true,
  match_json: {},  // Match all requests
  action_json: {
    add_warning: {
      message: 'Beta routing engine in use'
    }
  }
});

Python

rule = client.routing_rules.create(
    name="Always Warn About Beta",
    priority=-100,
    is_enabled=True,
    match_json={},  # Match all requests
    action_json={
        "add_warning": {"message": "Beta routing engine in use"}
    }
)

cURL

curl -X POST https://api.tokenrouter.io/v1/routing-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Always Warn About Beta",
    "priority": -100,
    "is_enabled": true,
    "match_json": {},
    "action_json": {
      "add_warning": {"message": "Beta routing engine in use"}
    }
  }'

Response

{
  "data": {
    "id": 123,
    "user_id": 456,
    "name": "Coding Tasks → OpenAI",
    "is_enabled": true,
    "priority": 100,
    "match_json": {
      "task": "coding"
    },
    "action_json": {
      "set_provider": "openai",
      "set_model": "gpt-4o"
    },
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T12:00:00Z"
  }
}

Error Responses

403 Forbidden - Free Plan

{
  "error": {
    "message": "Routing rules are not available on the free plan",
    "type": "authorization_error",
    "http_status": 403
  }
}

422 Validation Error

{
  "error": {
    "message": "Validation failed",
    "type": "validation_error",
    "http_status": 422,
    "errors": {
      "priority": ["The priority must be between -1000 and 1000"]
    }
  }
}

Best Practices

1. Use descriptive names - Make rule purposes clear
2. Set appropriate priorities - Higher values for more specific rules
3. Test with is_enabled: false - Test rules before activating
4. Use specific conditions - Avoid overly broad match conditions
5. Combine actions carefully - Only first provider/model/mode applies

Next Steps

• List Routing Rules
• Get Routing Rule
• Update Routing Rule
• Delete Routing Rule