> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humancheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Rules

> Configure intelligent routing of reviews to reviewers

Routing rules allow you to automatically assign reviews to specific reviewers based on conditions. This guide explains how to create and manage routing rules.

<Tabs>
  <Tab title="Open Source">
    Open Source uses **config-based routing** defined in `humancheck.yaml`. Simple YAML configuration for basic routing needs.
  </Tab>

  <Tab title="Platform">
    Platform provides **advanced routing** with:

    * **UI-based management** - Create and manage rules via dashboard
    * **Prioritization** - Fine-tune rule evaluation order
    * **Fine-grained ACL** - Control access and permissions per rule
    * **Database-backed** - Persistent rules with API access
  </Tab>
</Tabs>

## Overview

Routing rules evaluate reviews and assign them to reviewers based on:

* Task type
* Urgency level
* Confidence score
* Custom metadata
* Priority (rule evaluation order)

## Creating Routing Rules

### Open Source (Config-Based)

Configure routing rules in `humancheck.yaml`:

```yaml theme={null}
# Default reviewers (used when no rules match)
default_reviewers:
  - alice@example.com
  - bob@example.com

# Routing rules
routing_rules:
  - name: "High-value payments to finance team"
    priority: 100
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      metadata.amount: {"operator": ">", "value": 10000}
    assign_to: "finance@example.com"
    is_active: true
  
  - name: "Urgent reviews to on-call"
    priority: 200
    conditions:
      urgency: {"operator": "=", "value": "critical"}
    assign_to: "oncall@example.com"
    is_active: true
```

### Platform (UI-Based with API)

<Warning>
  Advanced routing with UI control, prioritization, and fine-grained ACL is only available in [Humancheck Platform](/platform/overview).
</Warning>

**Via Dashboard UI:**

1. Go to [platform.humancheck.dev](https://platform.humancheck.dev)
2. Navigate to **Routing** section
3. Click **Create Rule**
4. Configure conditions, priority, and ACL settings
5. Assign to users or teams with fine-grained permissions

**Via API:**

```python theme={null}
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://api.humancheck.dev/routing-rules",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
            "name": "High-value payments to finance team",
            "organization_id": 1,
            "priority": 100,
            "conditions": {
                "task_type": {"operator": "=", "value": "payment"},
                "metadata.amount": {"operator": ">", "value": 10000}
            },
            "assign_to_team_id": 5,  # Finance team
            "is_active": True
        }
    )
    rule = response.json()
```

**Platform Features:**

* ✅ **UI Control**: Visual rule builder in dashboard
* ✅ **Prioritization**: Set rule evaluation order
* ✅ **Fine-grained ACL**: Control who can view/edit/execute rules
* ✅ **Team/User Assignment**: Assign to specific teams or users
* ✅ **Organization Scoping**: Rules scoped to organizations

### Rule Structure

**Open Source (YAML):**

```yaml theme={null}
routing_rules:
  - name: "Rule name"
    priority: 100
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      urgency: {"operator": "in", "value": ["high", "critical"]}
    assign_to: "reviewer@example.com"  # Email or identifier
    is_active: true
```

**Platform (JSON):**

```json theme={null}
{
  "name": "Rule name",
  "organization_id": 1,
  "priority": 100,
  "conditions": {
    "task_type": {"operator": "=", "value": "payment"},
    "urgency": {"operator": "in", "value": ["high", "critical"]}
  },
  "assign_to_user_id": 2,
  "assign_to_team_id": 5,
  "is_active": true
}
```

## Condition Operators

### Equality

```python theme={null}
"task_type": {"operator": "=", "value": "payment"}
```

### Comparison

```python theme={null}
"confidence_score": {"operator": "<", "value": 0.8}
"metadata.amount": {"operator": ">", "value": 10000}
```

### In List

```python theme={null}
"urgency": {"operator": "in", "value": ["high", "critical"]}
"task_type": {"operator": "in", "value": ["payment", "data_deletion"]}
```

### Contains

```python theme={null}
"proposed_action": {"operator": "contains", "value": "DELETE"}
```

### Metadata Access

```python theme={null}
"metadata.amount": {"operator": ">", "value": 10000}
"metadata.user_id": {"operator": "=", "value": 123}
```

## Priority System

Rules are evaluated in priority order (highest first). The first matching rule is used.

```python theme={null}
# High priority (evaluated first)
{
    "priority": 200,
    "conditions": {"urgency": "critical"}
}

# Medium priority
{
    "priority": 100,
    "conditions": {"task_type": "payment"}
}

# Low priority (catch-all)
{
    "priority": 10,
    "conditions": {}
}
```

## Common Examples

### Route by Task Type

```python theme={null}
{
    "name": "SQL reviews to DBA team",
    "priority": 100,
    "conditions": {
        "task_type": {"operator": "=", "value": "sql_execution"}
    },
    "assign_to_team_id": 4
}
```

### Route by Urgency

```python theme={null}
{
    "name": "Critical reviews to on-call",
    "priority": 200,
    "conditions": {
        "urgency": {"operator": "=", "value": "critical"}
    },
    "assign_to_user_id": 10  # On-call user
}
```

### Route by Confidence

```python theme={null}
{
    "name": "Low confidence to senior reviewers",
    "priority": 100,
    "conditions": {
        "confidence_score": {"operator": "<", "value": 0.7}
    },
    "assign_to_team_id": 3  # Senior reviewers team
}
```

### Route by Metadata

```python theme={null}
{
    "name": "High-value payments to finance",
    "priority": 100,
    "conditions": {
        "task_type": {"operator": "=", "value": "payment"},
        "metadata.amount": {"operator": ">", "value": 10000}
    },
    "assign_to_team_id": 5
}
```

### Catch-All Rule

```python theme={null}
{
    "name": "Default assignment",
    "priority": 10,
    "conditions": {},  # Matches everything
    "assign_to_team_id": 1  # Default team
}
```

## Platform: UI-Based Routing

In Platform, you can manage routing rules entirely through the dashboard:

1. **Visual Rule Builder**: Create rules using drag-and-drop interface
2. **Prioritization**: Set rule evaluation order with visual priority controls
3. **Fine-Grained ACL**: Control who can view, edit, or execute each rule
4. **Team/User Management**: Assign reviews to teams or users with permission controls
5. **Rule Testing**: Test rules against sample reviews before activation
6. **Analytics**: Monitor rule performance and assignment accuracy

Access the routing management UI at [platform.humancheck.dev/routing](https://platform.humancheck.dev/routing).

## Best Practices

1. **Use priority wisely**: Higher priority rules should be more specific
2. **Create catch-all rules**: Ensure all reviews get assigned
3. **Test rules**: Test rules with sample reviews before going live
4. **Document rules**: Use descriptive names and comments
5. **Monitor assignments**: Check that reviews are being assigned correctly
6. **Platform**: Use UI for complex rule management, API for automation

## Next Steps

* Learn about [Configuration Settings](/configuration/settings)
* Explore [Multi-tenancy](/configuration/multi-tenancy)
* Check out [Dashboard](/dashboard/overview) for reviewing