Get Firewall Rule

Get Firewall Rule

Returns a single firewall rule by ID for the authenticated user.

Endpoint

GET /v1/firewall-rules/{id}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The firewall rule ID

Examples

TypeScript

import Tokenrouter from 'tokenrouter';

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

const rule = await client.firewallRules.retrieve(123);

console.log(`Rule: ${rule.data.name}`);
console.log(`Priority: ${rule.data.priority}`);
console.log(`Scope: ${rule.data.scope}`);
console.log(`Type: ${rule.data.type}`);
console.log(`Pattern: ${rule.data.pattern}`);
console.log(`Action: ${rule.data.action}`);
console.log(`Enabled: ${rule.data.is_enabled}`);

if (rule.data.replacement) {
  console.log(`Replacement: ${rule.data.replacement}`);
}

Python

from tokenrouter import Tokenrouter

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

rule = client.firewall_rules.retrieve(123)

print(f"Rule: {rule.data.name}")
print(f"Priority: {rule.data.priority}")
print(f"Scope: {rule.data.scope}")
print(f"Type: {rule.data.type}")
print(f"Pattern: {rule.data.pattern}")
print(f"Action: {rule.data.action}")
print(f"Enabled: {rule.data.is_enabled}")

if rule.data.replacement:
    print(f"Replacement: {rule.data.replacement}")

cURL

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

Response

{
  "data": {
    "id": 123,
    "user_id": 456,
    "name": "Block Credit Card Numbers",
    "is_enabled": true,
    "priority": 100,
    "scope": "prompt",
    "type": "regex",
    "pattern": "\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}",
    "action": "block",
    "replacement": null,
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T12: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)
scope	string	prompt or response
type	string	substring or regex
pattern	string	Pattern to match
action	string	block, mask, or warn
replacement	string|null	Replacement text (only for mask action)
created_at	string	ISO timestamp of creation
updated_at	string	ISO timestamp of last update

Error Responses

404 Not Found

Returned when the rule doesn’t exist or doesn’t belong to the authenticated user:

{
  "error": {
    "message": "Firewall rule not found",
    "type": "not_found_error",
    "http_status": 404
  }
}

Practical Examples

Check if Rule is Active

TypeScript

const rule = await client.firewallRules.retrieve(123);

if (rule.data.is_enabled) {
  console.log(`✓ Rule "${rule.data.name}" is active`);
  console.log(`  It will ${rule.data.action} content matching: ${rule.data.pattern}`);
} else {
  console.log(`✗ Rule "${rule.data.name}" is disabled`);
}

Python

rule = client.firewall_rules.retrieve(123)

if rule.data.is_enabled:
    print(f"✓ Rule \"{rule.data.name}\" is active")
    print(f"  It will {rule.data.action} content matching: {rule.data.pattern}")
else:
    print(f"✗ Rule \"{rule.data.name}\" is disabled")

Verify Rule Configuration

TypeScript

const rule = await client.firewallRules.retrieve(ruleId);

// Verify configuration
const checks = {
  'Has name': rule.data.name.length > 0,
  'Valid priority': rule.data.priority >= -1000 && rule.data.priority <= 1000,
  'Valid scope': ['prompt', 'response'].includes(rule.data.scope),
  'Valid type': ['substring', 'regex'].includes(rule.data.type),
  'Valid action': ['block', 'mask', 'warn'].includes(rule.data.action),
  'Has pattern': rule.data.pattern.length > 0,
  'Has replacement (if mask)': rule.data.action !== 'mask' || rule.data.replacement !== null
};

Object.entries(checks).forEach(([check, passed]) => {
  console.log(`${passed ? '✓' : '✗'} ${check}`);
});

Python

rule = client.firewall_rules.retrieve(rule_id)

# Verify configuration
checks = {
    "Has name": len(rule.data.name) > 0,
    "Valid priority": -1000 <= rule.data.priority <= 1000,
    "Valid scope": rule.data.scope in ["prompt", "response"],
    "Valid type": rule.data.type in ["substring", "regex"],
    "Valid action": rule.data.action in ["block", "mask", "warn"],
    "Has pattern": len(rule.data.pattern) > 0,
    "Has replacement (if mask)": rule.data.action != "mask" or rule.data.replacement is not None
}

for check, passed in checks.items():
    print(f"{'✓' if passed else '✗'} {check}")

Clone Rule for Editing

TypeScript

// Get existing rule
const original = await client.firewallRules.retrieve(123);

// Create a similar rule with modified settings
const cloned = await client.firewallRules.create({
  name: `${original.data.name} (Copy)`,
  priority: original.data.priority - 10,
  is_enabled: false,  // Start disabled for testing
  scope: original.data.scope,
  type: original.data.type,
  pattern: original.data.pattern,
  action: original.data.action,
  replacement: original.data.replacement
});

console.log(`Created cloned rule: ${cloned.data.id}`);

Python

# Get existing rule
original = client.firewall_rules.retrieve(123)

# Create a similar rule with modified settings
cloned = client.firewall_rules.create(
    name=f"{original.data.name} (Copy)",
    priority=original.data.priority - 10,
    is_enabled=False,  # Start disabled for testing
    scope=original.data.scope,
    type=original.data.type,
    pattern=original.data.pattern,
    action=original.data.action,
    replacement=original.data.replacement
)

print(f"Created cloned rule: {cloned.data.id}")

Compare Rules

TypeScript

const rule1 = await client.firewallRules.retrieve(123);
const rule2 = await client.firewallRules.retrieve(124);

console.log('Comparison:');
console.log(`Priority: ${rule1.data.priority} vs ${rule2.data.priority}`);
console.log(`Scope: ${rule1.data.scope} vs ${rule2.data.scope}`);
console.log(`Action: ${rule1.data.action} vs ${rule2.data.action}`);

if (rule1.data.priority > rule2.data.priority) {
  console.log(`\n"${rule1.data.name}" will be evaluated first`);
} else {
  console.log(`\n"${rule2.data.name}" will be evaluated first`);
}

Python

rule1 = client.firewall_rules.retrieve(123)
rule2 = client.firewall_rules.retrieve(124)

print("Comparison:")
print(f"Priority: {rule1.data.priority} vs {rule2.data.priority}")
print(f"Scope: {rule1.data.scope} vs {rule2.data.scope}")
print(f"Action: {rule1.data.action} vs {rule2.data.action}")

if rule1.data.priority > rule2.data.priority:
    print(f"\n\"{rule1.data.name}\" will be evaluated first")
else:
    print(f"\n\"{rule2.data.name}\" will be evaluated first")

Use Cases

Audit Individual Rule

const rule = await client.firewallRules.retrieve(ruleId);

console.log(`\nFirewall Rule Audit: ${rule.data.name}`);
console.log(`ID: ${rule.data.id}`);
console.log(`Status: ${rule.data.is_enabled ? 'Active' : 'Disabled'}`);
console.log(`Priority: ${rule.data.priority}`);
console.log(`Applies to: ${rule.data.scope === 'prompt' ? 'User input' : 'LLM responses'}`);
console.log(`Match method: ${rule.data.type === 'regex' ? 'Regular expression' : 'Substring'}`);
console.log(`Pattern: ${rule.data.pattern}`);
console.log(`Action: ${rule.data.action.toUpperCase()}`);

if (rule.data.action === 'mask' && rule.data.replacement) {
  console.log(`Replacement text: ${rule.data.replacement}`);
}

console.log(`Created: ${new Date(rule.data.created_at).toLocaleString()}`);
console.log(`Last updated: ${new Date(rule.data.updated_at).toLocaleString()}`);

Monitor Rule Age

const rule = await client.firewallRules.retrieve(ruleId);

const createdDate = new Date(rule.data.created_at);
const updatedDate = new Date(rule.data.updated_at);
const now = new Date();

const daysSinceCreation = Math.floor((now.getTime() - createdDate.getTime()) / (1000 * 60 * 60 * 24));
const daysSinceUpdate = Math.floor((now.getTime() - updatedDate.getTime()) / (1000 * 60 * 60 * 24));

console.log(`Rule age: ${daysSinceCreation} days`);
console.log(`Last updated: ${daysSinceUpdate} days ago`);

if (daysSinceUpdate > 90) {
  console.log('⚠️  Rule hasn\'t been reviewed in over 90 days');
}

Next Steps

• Update Firewall Rule
• Delete Firewall Rule
• List All Rules
• Create New Rule