Pools & Recipients

Pools and recipients are the targets a routing decision chooses from — a pool is the market a unit of Work enters, and its recipients are the candidate Workers. A pool is a container: it has a selection strategy, a kill-switch, and configuration, but no capacity of its own. A recipient is a concrete endpoint inside one or more pools — an agent, team, queue, or downstream system — and it's where capacity and availability actually live. When the routing pipeline runs, it loads a pool, filters its recipients down to the eligible ones, and hands them to a strategy to pick a winner.

Pools

The pool object

A pool routes only when it is active and its kill-switch is off — internally CanRoute() = IsActive() && !IsKillSwitchActive(). A paused or disabled pool, or one with the kill-switch engaged, is skipped.

Create a pool

CreatePool — POST /api/pools (pool:write):

curl -s -X POST https://api.ductor.io/api/pools \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-agents",
    "description": "Tier-2 billing support",
    "strategy": "smooth_weighted_round_robin",
    "status": "STATUS_ACTIVE",
    "config": {
      "routing_mode": "auto",
      "default_timeout": "30s",
      "max_routing_depth": 3
    },
    "metadata": { "team": "billing" }
  }'

{
  "data": {
    "id": "3f1e2d3c-...",
    "name": "billing-agents",
    "status": "STATUS_ACTIVE",
    "strategy": "smooth_weighted_round_robin",
    "config": { "routing_mode": "auto", "default_timeout": "30s", "max_routing_depth": 3 },
    "recipient_ids": [],
    "record_version": 0,
    "created_at": "2026-07-11T10:45:00Z"
  }
}

The PoolConfig surface

PoolConfig (domain/pool/config.go) is a large struct. Grouped by what they control:

Strategy selection (mutually exclusive authoring inputs — pick one):

Routing behavior and limits:

Fallback, overflow, and capacity headroom:

Claim mode and kill-switch:

Read pools

# One pool
curl -s https://api.ductor.io/api/pools/$POOL_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

# List, optionally filtered by status
curl -s "https://api.ductor.io/api/pools?status=STATUS_ACTIVE&pagination.page_size=50" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

GetPool and ListPools require pool:read. List responses paginate with the standard pagination cursor.

Update a pool

UpdatePool — PATCH /api/pools/{pool_id} (pool:write) — is a partial update; only the fields you send change.

curl -s -X PATCH https://api.ductor.io/api/pools/$POOL_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "strategy": "weighted_round_robin", "config": { "default_timeout": "45s" } }'

The kill-switch: SetPoolEnabled

SetPoolEnabled — POST /api/pools/{pool_id}:set_enabled (pool:write) — toggles the pool kill-switch atomically with optimistic concurrency. This is the operator's emergency stop for a pool: flip enabled: false and the pool stops routing immediately without deleting anything.

curl -s -X POST "https://api.ductor.io/api/pools/$POOL_ID:set_enabled" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "expected_version": 4, "reason": "provider outage — halting dispatch" }'

• enabled: false engages the kill-switch (routing off); true clears it.
• expected_version is the last record_version you read. If the stored version has moved on, the call fails with 412 Failed Precondition — re-read and retry. Pass 0 to skip the version guard.
• reason (max 4096 chars) is stamped on the audit trail and onto config.kill_switch_reason.

The response returns the pool with its incremented record_version.

Pool stats and capacity reset

GetPoolStats — GET /api/pools/{pool_id}/stats (pool:read) — returns operational metrics aggregated from the pool's recipients:

{
  "data": {
    "pool_id": "3f1e2d3c-...",
    "total_recipients": 12,
    "active_recipients": 9,
    "total_capacity": 120,
    "used_capacity": 84,
    "utilization": 0.70,
    "queue_depth": 3,
    "updated_at": "2026-07-11T10:50:00Z"
  }
}

ResetPoolCapacity — POST /api/pools/{pool_id}/capacity/reset (pool:write) — clears the in-flight and daily counters for every recipient in the pool and returns how many were affected. Use it to recover from counter drift or to start a fresh daily window manually.

Delete a pool

DeletePool — DELETE /api/pools/{pool_id} (pool:delete) — removes the pool and disassociates its recipients (the recipients themselves survive; only their membership in this pool is dropped).

Recipients

A recipient is the routable endpoint. It has state (is it available?), capacity (does it have room?), a weight (how much traffic it should get relative to peers), and attributes (the key/value data your rules evaluate).

The recipient object

Recipient state

RecipientState is the live availability signal, distinct from the administrative status:

A recipient is eligible when state == AVAILABLE and it is not at capacity. That's the filter the pipeline applies before a strategy ever sees the candidate.

Capacity

A recipient is at capacity when current >= max_concurrent, or when daily_limit > 0 && daily_count >= daily_limit (Capacity.IsAtCapacity). The domain exposes the derived views the engine uses: AvailableCapacity() (the smaller of concurrent and daily headroom), HasRoom() (any headroom left), and Utilization() (current / max_concurrent, 0–1). The daily counter resets after a rolling 24 hours (NeedsReset / Reset), or manually via ResetPoolCapacity.

Capacity limits and over-capacity

By default an at-capacity recipient is filtered out of the eligible set — it simply won't be selected. A pool can opt into controlled over-subscription:

• allow_over_capacity: true permits routing to an at-capacity recipient.
• over_capacity_budget (a percentage) bounds how far past capacity the pool will push before it stops.

Use this when a short, bounded burst is preferable to queuing or dropping — for example, letting a hot pool absorb a spike rather than overflow it. Without these flags, capacity is a hard gate.

Create a recipient

CreateRecipient — POST /api/pools/{pool_id}/recipients (recipient:write). The pool comes from the path.

curl -s -X POST https://api.ductor.io/api/pools/$POOL_ID/recipients \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Reyes",
    "type": "agent",
    "external_id": "agent-4471",
    "state": "RECIPIENT_STATE_AVAILABLE",
    "weight": 2.0,
    "capacity": { "max_concurrent": 5, "daily_limit": 40 },
    "tags": ["billing", "spanish"],
    "attributes": {
      "skill": { "string_value": "billing" },
      "seniority": { "number_value": 3 },
      "vip_certified": { "bool_value": true }
    },
    "timezone": "America/Chicago"
  }'

Read, update, delete recipients

# Get one
curl -s https://api.ductor.io/api/recipients/$RECIPIENT_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

# List within a pool, filter by status and state
curl -s "https://api.ductor.io/api/pools/$POOL_ID/recipients?state=RECIPIENT_STATE_AVAILABLE" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

UpdateRecipient — PATCH /api/recipients/{recipient_id} (recipient:write) — is a partial update. Setting pool_id moves the recipient's primary pool.

curl -s -X PATCH https://api.ductor.io/api/recipients/$RECIPIENT_ID \
  -H "Authorization: Bearer $DUCTOR_API_KEY" \
  -H "X-Tenant-ID: $DUCTOR_TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "weight": 1.5, "capacity": { "max_concurrent": 8 } }'

DeleteRecipient — DELETE /api/recipients/{recipient_id} (recipient:delete).

Pause and resume

Two dedicated verbs flip availability without a full update — the common operational lever for taking a recipient out of rotation:

# Take out of rotation → RECIPIENT_STATE_PAUSED
curl -s -X POST https://api.ductor.io/api/recipients/$RECIPIENT_ID/pause \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

# Put back → RECIPIENT_STATE_AVAILABLE
curl -s -X POST https://api.ductor.io/api/recipients/$RECIPIENT_ID/resume \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

Both require recipient:write. A paused recipient stays a member of its pools and keeps its capacity counters — it's simply skipped by the eligibility filter until resumed.

Fallback behavior

When a routing pass finds no eligible recipient, config.fallback (domain/pool/fallback.go) decides what happens to the work:

overflow and catchall require a target pool (RequiresTargetPool) — set the matching *_pool_id, or config validation rejects the pool. Overflow and catchall hops count against max_routing_depth, so a chain of spill-over pools can't loop forever.

SLA / speed-to-lead

config.sla (SLAConfig, domain/pool/sla.go) puts a clock on a pool — the "speed-to-lead" guarantee that a routable is picked up and responded to quickly:

The pool config is the policy; two strategy building blocks enforce and rescue against it: the sla_deadline strategy ranks candidates by deadline headroom (who can beat the clock with the most room), and the sla_rescue recipe pairs sla_deadline with an availability fallback so breaching work still lands somewhere.

Routing modes: auto vs claim

config.routing_mode (domain/pool/routing_mode.go) chooses how an item reaches a recipient:

• auto (default) — the engine selects a winner and assigns the item to it. This is push routing: the strategy decides.
• claim — the engine places the item in a shared claim queue (claim_queue_id, required) and recipients self-select ("lead ponds"). The decision outcome is queued_for_claim rather than an assignment, and each recipient's claiming is bounded by a claim.Budget (claims per period). The shark_tank strategy is the classic claim pattern: it broadcasts the item to the pool and then awaits a claim.

How routing consumes them

At decision time the pipeline calls the pool port, which loads the pool together with its recipients (LoadPoolData → pool + recipients, served from a pub/sub-invalidated cache on the hot path). The pipeline then:

1. Checks the pool can route (active && !kill_switch).
2. Filters recipients to the eligible set (state == AVAILABLE && !at capacity), applying schedules and rule filters.
3. Hands the survivors to the pool's strategy, which returns the winner.
4. On assignment, the winner's capacity counters increment.

So the levers you manage here map directly onto routing behavior: state and capacity gate eligibility, weight and attributes shape which eligible recipient wins, and the pool strategy decides how.

Bulk topology changes

To apply an entire pool/recipient/rule topology atomically — idempotent by name, all-or-nothing in one transaction — use the routing bundle endpoints (ApplyRoutingBundle / DiffRoutingBundle under /api/routing/bundle). They're the right tool for declarative, GitOps-style management of your routing graph rather than imperative per-resource calls.

Where to go next