Routing Rules API - Programmatic AI Routing Control

Overview

The Routing Rules API allows you to programmatically create and manage custom routing rules that control how TokenRouter selects AI providers and models for your requests.

Paid Feature

Custom routing rules are only available on paid plans. Free plan users can view but not create, update, or delete rules.

Supported Providers

TokenRouter currently supports the following providers for routing rules:

• openai - OpenAI (GPT-4o, GPT-4, GPT-3.5)
• anthropic - Anthropic (Claude 3.7, Claude 3.5, Claude 3)
• gemini - Google Gemini
• mistral - Mistral AI
• deepseek - DeepSeek

Supported Modes

• balance - Balanced routing (default)
• cost - Cost-optimized routing
• quality - Quality-optimized routing
• latency - Latency-optimized routing

---

List Routing Rules

GET https://api.tokenrouter.io/v1/routing-rules

Returns all routing rules for the authenticated user, ordered by priority (highest first).

TypeScript

const response = await fetch('https://api.tokenrouter.io/v1/routing-rules', {
  headers: {
    'Authorization': 'Bearer tr_...',
  }
});

const { data } = await response.json();
console.log(`Found ${data.length} routing rules`);

Python

import requests

response = requests.get(
    'https://api.tokenrouter.io/v1/routing-rules',
    headers={'Authorization': 'Bearer tr_...'}
)

data = response.json()['data']
print(f"Found {len(data)} routing rules")

cURL

curl https://api.tokenrouter.io/v1/routing-rules \
  -H "Authorization: Bearer tr_..."

Response

{
  "data": [
    {
      "id": 1,
      "user_id": 123,
      "name": "Force Anthropic for Code",
      "is_enabled": true,
      "priority": 100,
      "match_json": {
        "contains": ["code", "function", "programming"]
      },
      "action_json": {
        "set_provider": "anthropic",
        "set_model": "claude-3-7-sonnet-latest"
      },
      "created_at": "2025-09-13T19:14:17.000000Z",
      "updated_at": "2025-09-13T19:14:17.000000Z"
    }
  ]
}

---

Create Routing Rule

POST https://api.tokenrouter.io/v1/routing-rules

Creates a new routing rule.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable name (max 128 chars)
is_enabled	boolean	Yes	Whether the rule is active
priority	integer	Yes	Priority (-1000 to 1000, higher = first)
match_json	object	Yes	Conditions for matching
action_json	object	Yes	Actions to take when matched

Match Conditions

All conditions are combined with AND logic - every specified condition must match for the rule to trigger.

Condition	Type	Description	Example
contains	string or array	Search for text in user input (case-insensitive substring match)	"code" or ["code", "function"]
metadata_equals	object	Match metadata key-value pairs (exact match)	{"user_tier": "premium"}
mode	string	Match routing mode (case-insensitive)	"balance", "cost", "quality", "latency"
task	string	Shorthand for metadata_equals.task (case-sensitive)	"summarize"

Notes:

• contains searches anywhere in the input text (if array, matches if ANY value found)
• Input is normalized: objects/arrays are JSON-encoded before matching
• Empty strings in contains array are ignored

Actions

Once set, actions cannot be overridden by lower-priority rules.

Action	Type	Description	Notes
set_provider	string	Force specific provider	Lowercase: openai, anthropic, gemini, mistral, deepseek
set_model	string	Force specific model	Full model name: claude-3-7-sonnet-latest, gpt-4o
set_mode	string	Override routing mode	Lowercase: balance, cost, quality, latency
add_warning	string or object	Add custom warning	String or {"message": "text"}

Action Precedence:

• First matching rule that sets set_provider wins - subsequent rules cannot change it
• Same applies for set_model and set_mode
• add_warning can be set by multiple rules (accumulates)
• Skipped actions are logged in rule trace with reason

Examples

Route Code Questions to Anthropic

TypeScript

const response = await fetch('https://api.tokenrouter.io/v1/routing-rules', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tr_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: "Force Anthropic for Code",
    is_enabled: true,
    priority: 100,
    match_json: {
      contains: ["code", "function", "programming"]
    },
    action_json: {
      set_provider: "anthropic",
      set_model: "claude-3-7-sonnet-latest"
    }
  })
});

const { data } = await response.json();
console.log(`Created rule: ${data.name}`);

Python

import requests

response = requests.post(
    'https://api.tokenrouter.io/v1/routing-rules',
    headers={'Authorization': 'Bearer tr_...'},
    json={
        "name": "Force Anthropic for Code",
        "is_enabled": True,
        "priority": 100,
        "match_json": {
            "contains": ["code", "function", "programming"]
        },
        "action_json": {
            "set_provider": "anthropic",
            "set_model": "claude-3-7-sonnet-latest"
        }
    }
)

data = response.json()['data']
print(f"Created rule: {data['name']}")

cURL

curl -X POST https://api.tokenrouter.io/v1/routing-rules \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Force Anthropic for Code",
    "is_enabled": true,
    "priority": 100,
    "match_json": {
      "contains": ["code", "function", "programming"]
    },
    "action_json": {
      "set_provider": "anthropic",
      "set_model": "claude-3-7-sonnet-latest"
    }
  }'

Cost Optimization for Summaries

{
  "name": "Cost-optimize summaries",
  "is_enabled": true,
  "priority": 50,
  "match_json": {
    "metadata_equals": {
      "task": "summarize"
    }
  },
  "action_json": {
    "set_mode": "cost"
  }
}

Multiple Conditions (AND logic)

{
  "name": "Research in balanced mode",
  "is_enabled": true,
  "priority": 60,
  "match_json": {
    "contains": "research",
    "mode": "balanced"
  },
  "action_json": {
    "set_mode": "quality",
    "set_provider": "anthropic"
  }
}

---

Get Routing Rule

GET https://api.tokenrouter.io/v1/routing-rules/{id}

Returns a single routing rule by ID.

TypeScript

const response = await fetch('https://api.tokenrouter.io/v1/routing-rules/1', {
  headers: {
    'Authorization': 'Bearer tr_...',
  }
});

const { data } = await response.json();

Python

response = requests.get(
    'https://api.tokenrouter.io/v1/routing-rules/1',
    headers={'Authorization': 'Bearer tr_...'}
)

data = response.json()['data']

cURL

curl https://api.tokenrouter.io/v1/routing-rules/1 \
  -H "Authorization: Bearer tr_..."

---

Update Routing Rule

PATCH https://api.tokenrouter.io/v1/routing-rules/{id}

Updates an existing routing rule. All fields are optional.

Examples

Disable a Rule

TypeScript

await fetch('https://api.tokenrouter.io/v1/routing-rules/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer tr_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    is_enabled: false
  })
});

Python

requests.patch(
    'https://api.tokenrouter.io/v1/routing-rules/1',
    headers={'Authorization': 'Bearer tr_...'},
    json={"is_enabled": False}
)

cURL

curl -X PATCH https://api.tokenrouter.io/v1/routing-rules/1 \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

Update Priority

{
  "priority": 150
}

Update Actions

{
  "action_json": {
    "set_provider": "openai",
    "set_model": "gpt-4o"
  }
}

---

Delete Routing Rule

DELETE https://api.tokenrouter.io/v1/routing-rules/{id}

Permanently deletes a routing rule.

TypeScript

await fetch('https://api.tokenrouter.io/v1/routing-rules/1', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer tr_...',
  }
});

Python

requests.delete(
    'https://api.tokenrouter.io/v1/routing-rules/1',
    headers={'Authorization': 'Bearer tr_...'}
)

cURL

curl -X DELETE https://api.tokenrouter.io/v1/routing-rules/1 \
  -H "Authorization: Bearer tr_..."

Response

{
  "success": true
}

---

Real-World Examples

Example 1: Route Legal Questions to GPT-4o

{
  "name": "Legal content → GPT-4o",
  "is_enabled": true,
  "priority": 90,
  "match_json": {
    "contains": ["legal", "contract", "compliance", "regulation"]
  },
  "action_json": {
    "set_provider": "openai",
    "set_model": "gpt-4o"
  }
}

When it matches:

• Input contains “legal”, “contract”, “compliance”, or “regulation”

What it does:

• Routes to OpenAI’s GPT-4o model

Example 2: Use DeepSeek for Cost-Sensitive Tasks

{
  "name": "Cost mode → DeepSeek",
  "is_enabled": true,
  "priority": 75,
  "match_json": {
    "mode": "cost"
  },
  "action_json": {
    "set_provider": "deepseek"
  }
}

When it matches:

• Request uses auto:cost or mode is set to cost

What it does:

• Routes to DeepSeek (most cost-effective)

Example 3: Premium Users Get Quality Mode

{
  "name": "Premium users → Quality",
  "is_enabled": true,
  "priority": 80,
  "match_json": {
    "metadata_equals": {
      "user_tier": "premium"
    }
  },
  "action_json": {
    "set_mode": "quality",
    "add_warning": {
      "message": "Premium user - using quality routing"
    }
  }
}

When it matches:

• Request metadata includes user_tier: "premium"

What it does:

• Switches to quality mode
• Adds a warning message to the response

---

Rule Evaluation Order

Rules are evaluated in the following order:

1. Priority (descending) - Higher priority rules evaluated first
2. ID (ascending) - Older rules evaluated first for same priority
3. All rules are checked - Multiple rules can match the same request
4. Action precedence - First rule to set an action wins for that action type

Important

Multiple rules can match and apply different actions:

• If Rule A (priority 100) sets set_provider: "openai", Rule B (priority 50) cannot change the provider
• However, Rule B can still set set_mode or add warnings if Rule A didn’t set those
• Each action type (set_provider, set_model, set_mode) can only be set once (first matching rule wins)
• add_warning accumulates - multiple rules can add warnings

Evaluation continues even after a match - all enabled rules are evaluated unless an action was already set.

Error Responses

400 Bad Request

{
  "error": {
    "message": "The name field is required."
  }
}

403 Forbidden

{
  "error": {
    "message": "Custom routing rules require a paid plan."
  }
}

404 Not Found

{
  "error": {
    "message": "Routing rule not found"
  }
}

Next Steps

• Firewall Rules API
• Auto Routing
• Console Routing Rules