List Routing Rules

List Routing Rules

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

Endpoint

GET /v1/routing-rules

Query Parameters

None. This endpoint returns all rules for the authenticated user.

Examples

TypeScript

import Tokenrouter from 'tokenrouter';

const client = new Tokenrouter({
  apiKey: process.env.TOKENROUTER_API_KEY
});

const response = await client.routingRules.list();

// Rules are ordered by priority (highest first)
response.data.forEach(rule => {
  console.log(`${rule.name} (Priority: ${rule.priority})`);
  console.log(`Enabled: ${rule.is_enabled}`);
  console.log(`Conditions:`, rule.match_json);
  console.log(`Actions:`, rule.action_json);
  console.log('---');
});

Python

from tokenrouter import Tokenrouter

client = Tokenrouter(
    api_key=os.getenv("TOKENROUTER_API_KEY")
)

response = client.routing_rules.list()

# Rules are ordered by priority (highest first)
for rule in response.data:
    print(f"{rule.name} (Priority: {rule.priority})")
    print(f"Enabled: {rule.is_enabled}")
    print(f"Conditions: {rule.match_json}")
    print(f"Actions: {rule.action_json}")
    print("---")

cURL

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

Response

{
  "data": [
    {
      "id": 123,
      "user_id": 456,
      "name": "High Priority Code Review",
      "is_enabled": true,
      "priority": 100,
      "match_json": {
        "task": "code_review"
      },
      "action_json": {
        "set_provider": "anthropic",
        "set_model": "claude-3-5-sonnet-20241022"
      },
      "created_at": "2025-11-10T12:00:00Z",
      "updated_at": "2025-11-10T12:00:00Z"
    },
    {
      "id": 124,
      "user_id": 456,
      "name": "Cost Mode for Documentation",
      "is_enabled": true,
      "priority": 50,
      "match_json": {
        "contains": ["documentation", "docs"]
      },
      "action_json": {
        "set_mode": "cost"
      },
      "created_at": "2025-11-10T13:00:00Z",
      "updated_at": "2025-11-10T13:00:00Z"
    },
    {
      "id": 125,
      "user_id": 456,
      "name": "Disabled Test Rule",
      "is_enabled": false,
      "priority": 10,
      "match_json": {
        "mode": "quality"
      },
      "action_json": {
        "set_provider": "openai"
      },
      "created_at": "2025-11-10T14:00:00Z",
      "updated_at": "2025-11-10T14:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Unique rule identifier
user_id	integer	Owner user ID
name	string	Rule name
is_enabled	boolean	Whether rule is active
priority	integer	Rule priority (-1000 to 1000)
match_json	object	Match conditions
action_json	object	Actions to apply
created_at	string	ISO timestamp of creation
updated_at	string	ISO timestamp of last update

Rule Ordering

Rules are returned in the order they will be evaluated during routing:

1. By Priority (DESC) - Highest priority first
2. By ID (ASC) - Older rules first when priorities are equal

Example order:

Priority 100 → Evaluated first
Priority 50  → Evaluated second
Priority 10  → Evaluated third
Priority -100 → Evaluated last

Filtering Active Rules

TypeScript

const response = await client.routingRules.list();

// Get only enabled rules
const activeRules = response.data.filter(rule => rule.is_enabled);

console.log(`${activeRules.length} active rules`);

Python

response = client.routing_rules.list()

# Get only enabled rules
active_rules = [rule for rule in response.data if rule.is_enabled]

print(f"{len(active_rules)} active rules")

Empty Response

If no rules exist, the response is an empty array:

{
  "data": []
}

Practical Examples

Check for Specific Rule

TypeScript

const response = await client.routingRules.list();

const codingRule = response.data.find(
  rule => rule.match_json.task === 'coding' && rule.is_enabled
);

if (codingRule) {
  console.log('Found coding rule:', codingRule.name);
} else {
  console.log('No active coding rule found');
}

Python

response = client.routing_rules.list()

coding_rule = next(
    (rule for rule in response.data
     if rule.match_json.get('task') == 'coding' and rule.is_enabled),
    None
)

if coding_rule:
    print(f"Found coding rule: {coding_rule.name}")
else:
    print("No active coding rule found")

Count Rules by Priority Range

TypeScript

const response = await client.routingRules.list();

const highPriority = response.data.filter(r => r.priority >= 50).length;
const lowPriority = response.data.filter(r => r.priority < 0).length;

console.log(`High priority rules: ${highPriority}`);
console.log(`Low priority rules: ${lowPriority}`);

Python

response = client.routing_rules.list()

high_priority = len([r for r in response.data if r.priority >= 50])
low_priority = len([r for r in response.data if r.priority < 0])

print(f"High priority rules: {high_priority}")
print(f"Low priority rules: {low_priority}")

Next Steps

• Get Routing Rule
• Create Routing Rule
• Update Routing Rule
• Delete Routing Rule