Rules API Overview

Overview

The Rules API allows you to create custom routing logic that determines how TokenRouter routes your requests. Routing rules are evaluated before provider selection and can override the default routing behavior.

What are Routing Rules?

Routing rules let you define conditions that, when matched, trigger specific actions like:

Forcing a specific provider (e.g., always use OpenAI for coding tasks)
Overriding the routing mode (e.g., switch to cost mode for documentation)
Setting a specific model (e.g., use GPT-4 for complex analysis)
Adding warnings to responses

Rule Evaluation

Rules are evaluated in priority order (highest first):

Rules with higher priority values execute first
When multiple rules match, the first matching rule’s actions take precedence
Only enabled rules are evaluated (is_enabled: true)
Rules are evaluated before firewall rules in the routing pipeline

Base Endpoint

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

Authentication

All Rules API endpoints require authentication using your TokenRouter API key:

Authorization: Bearer tr_your_api_key

Common Operations

Operation	Method	Endpoint
List all rules	`GET`	`/v1/routing-rules`
Get single rule	`GET`	`/v1/routing-rules/{id}`
Create rule	`POST`	`/v1/routing-rules`
Update rule	`PATCH`	`/v1/routing-rules/{id}`
Delete rule	`DELETE`	`/v1/routing-rules/{id}`

Rule Structure

Match Conditions (`match_json`)

Define when a rule should be applied:

{
  "contains": "code review",          // Input contains text (case-insensitive)
  "metadata_equals": {                // Metadata key-value matches
    "task": "documentation"
  },
  "mode": "balanced",                 // Routing mode equals
  "task": "coding"                    // Shorthand for metadata_equals.task
}

All conditions must match for the rule to apply (AND logic).

Actions (`action_json`)

Define what happens when a rule matches:

{
  "set_provider": "openai",           // Force specific provider
  "set_model": "gpt-4o",             // Force specific model
  "set_mode": "cost",                 // Override routing mode
  "add_warning": {                    // Add warning message
    "message": "Using cost-optimized routing"
  }
}

Quick Start Example

import Tokenrouter from 'tokenrouter';

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

// Create a rule to use Anthropic for code review tasks
const rule = await client.routingRules.create({
  name: 'Code Review → Anthropic',
  priority: 100,
  is_enabled: true,
  match_json: {
    task: 'code_review'
  },
  action_json: {
    set_provider: 'anthropic',
    set_model: 'claude-3-5-sonnet-20241022'
  }
});

from tokenrouter import Tokenrouter

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

# Create a rule to use Anthropic for code review tasks
rule = client.routing_rules.create(
    name="Code Review → Anthropic",
    priority=100,
    is_enabled=True,
    match_json={"task": "code_review"},
    action_json={
        "set_provider": "anthropic",
        "set_model": "claude-3-5-sonnet-20241022"
    }
)

curl https://api.tokenrouter.io/v1/routing-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_..." \
  -d '{
    "name": "Code Review → Anthropic",
    "priority": 100,
    "is_enabled": true,
    "match_json": {
      "task": "code_review"
    },
    "action_json": {
      "set_provider": "anthropic",
      "set_model": "claude-3-5-sonnet-20241022"
    }
  }'

Response Metadata

When a routing rule is applied, the response includes metadata:

{
  "metadata": {
    "applied_rules": ["Code Review → Anthropic"],
    "routing_mode": "balanced",
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20241022"
  }
}