Rules

A rule is a CEL expression attached to a pool that shapes a routing decision — filtering candidates, boosting weights, or redirecting to another pool. Rules are how routing logic changes without a redeploy: you edit a rule over the API and the change propagates to every pod through cache invalidation. This page covers the rule lifecycle and the hot-reload mechanism that makes edits take effect immediately.

Why rules exist as a separate resource

Pools and recipients describe who can receive work. Rules describe the policy layered on top — "VIP leads skip tier-2," "route Spanish tickets to bilingual agents," "after 6pm, overflow to the on-call pool." Keeping that policy in versioned, hot-reloadable rules means product and ops can change routing behavior at runtime, and every change is a small, auditable diff rather than a code change.

The rule object

Rule actions

RuleAction says what happens when the rule matches:

Levels

level scopes where a rule applies: TENANT rules apply across the tenant, POOL rules to a single pool (the default; an empty level is treated as pool level), and SUB_POOL to a sub-pool within a hierarchy.

Writing the CEL expression

Rules evaluate against the routing context. The engine binds the variable set routable, recipient, now (pkg/celengine VarsRoutableRecipientNow, "used by: rule engine"). Both routable and recipient are maps, so you read their fields — and your typed attributes — by name.

The CEL environment

attributes on both sides is where your own key/value data lives — the typed Values you set on recipients and on the incoming routable. Everything else is a first-class field.

// Only bilingual billing agents for Spanish-language billing tickets
recipient.attributes.skill == "billing" && recipient.attributes.language == "es"

// High-priority work prefers senior agents with room to spare.
// routable.priority is a NUMBER — compare it numerically, not to a string.
routable.priority >= 8 && recipient.attributes.seniority >= 3

// Tier is your own attribute (a string), so read it from attributes
routable.attributes.tier == "vip" && recipient.capacity.current < recipient.capacity.max_concurrent

Create a rule

CreateRule — POST /api/pools/{pool_id}/rules (rule:write). There's also an additional binding at POST /api/rules if you'd rather pass the pool in the body.

curl -s -X POST https://api.ductor.io/api/pools/$POOL_ID/rules \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vip-to-senior",
    "cel_expression": "routable.attributes.tier == \"vip\" && recipient.attributes.seniority >= 3",
    "condition": "VIP work goes to senior agents",
    "priority": 10,
    "enabled": true,
    "stop": false,
    "level": "RULE_LEVEL_POOL",
    "actions": [ { "type": "filter" } ]
  }'

{
  "data": {
    "id": "7a6b5c4d-...",
    "name": "vip-to-senior",
    "pool_id": "3f1e2d3c-...",
    "cel_expression": "routable.attributes.tier == \"vip\" && recipient.attributes.seniority >= 3",
    "priority": 10,
    "enabled": true,
    "version": 1,
    "level": "RULE_LEVEL_POOL",
    "created_at": "2026-07-11T11:00:00Z"
  }
}

Validate before you save

ValidateRule — POST /api/rules/validate (rule:read) — checks a CEL expression for syntax and type errors without persisting anything. Wire this into your admin UI or CI so a bad expression is caught before it reaches a pool.

curl -s -X POST https://api.ductor.io/api/rules/validate \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "cel_expression": "recipient.attributes.skill == \"billing\"" }'

{ "valid": true, "error": "", "message": "expression is valid" }

An invalid expression returns valid: false with the parser error in error.

Read, update, delete

# One rule
curl -s https://api.ductor.io/api/rules/$RULE_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

# Rules in a pool, filter by enabled
curl -s "https://api.ductor.io/api/pools/$POOL_ID/rules?enabled=true" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

GetRule and ListRules require rule:read.

UpdateRule — PATCH /api/rules/{rule_id} (rule:write) — partial update. Toggling enabled is the fast way to disable a rule without deleting it; setting pool_id retargets it to another pool.

# Disable a rule without losing it
curl -s -X PATCH https://api.ductor.io/api/rules/$RULE_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

DeleteRule — DELETE /api/rules/{rule_id} (rule:delete).

Priority, stop, and evaluation order

Rules on a pool are evaluated in ascending priority (lower first). Each matching rule contributes its actions. A rule with stop: true halts evaluation of the remaining rules once it matches — use it for terminal decisions like a redirect where later rules shouldn't second-guess the outcome.

Hot reload: how edits take effect live

Rules are read on the routing hot path through a per-pool cache (LRU + TTL). When you create, update, or delete a rule, the cache entry for that pool must be dropped everywhere — not just on the pod that served your API call — or other pods would keep routing on the stale rule set.

Ductor handles this with pub/sub invalidation:

The result is a redeploy-free change that converges across the fleet within the propagation budget, with no pod left serving stale rules. This is the same invalidation pattern described in Connectors and the cache and the routing pipeline; rules and pool config each ride their own channel.

Versioning and audit

Every change bumps the rule's version, and prior versions are retained in rule_versions. That history is your audit trail for "who changed routing and when" and the basis for rolling a rule back to a known-good expression.

Where to go next