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) — resets committed assignment and daily counters for every recipient in the pool and returns how many were affected. Active workflow reservations are separate and remain held. Resetting counters cannot release a waiting workflow; use supported workflow completion or cancellation and wait for its descendants to finish.

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

capacity.current reports committed assignments. Selecting workflows hold additional durable reservations, so this counter alone does not show total admission occupancy. A zero counter does not prove a recipient has room for another workflow. daily_count reports committed daily assignments; current-day reservations also count toward workflow admission.

Capacity limits and over-capacity

Candidate filtering uses capacity and availability to form an eligible set. allow_over_capacity and over_capacity_budget can influence advisory candidate selection, but cannot raise a persisted hard limit. Assignment increments, batch assignments, and confirmation all enforce the hard limit before committing work. A candidate appearing in a selection preview is not an admission grant.

Capacity admission for selecting workflows

A selecting workflow durably reserves its entire selected or ranked slate before exposing selection output or starting a selected body. This applies to both strategy selection and the routing pipeline. Concurrent admission counts active reservations plus committed assignments. Daily admission counts reservations made in the current day plus committed daily assignments.

The effective concurrency ceiling uses the smaller positive value from the workflow's pinned configuration and the current live recipient configuration. An unlimited value cannot override a positive limit in the other configuration. Tightening a live concurrency limit therefore constrains an already published workflow's next admission.

Daily admission uses the recipient's current live daily_limit and the UTC calendar day. Reservations admitted that day still count after they are released, alongside committed daily assignments. Completion or cancellation does not refund that day's admission budget.

recipient_capacity_exhausted means admission was refused for capacity. capacity_authority_unavailable means the required capacity authority could not be used. Neither means there were simply no eligible recipients. Inspect the run snapshot and step error; a failed or stale observation cannot establish an empty backlog. A refused admission exposes no partial slate and starts no selected body.

Reservations remain held until the selecting workflow and all persisted descendants and continuations are terminal. An approval wait, a nested body, a server restart, or elapsed time does not release them. Cancellation acceptance alone is not release: wait for child work to drain. Reservation correctness does not depend on a time-to-live.

Continue-as-new keeps earlier reservations held throughout the continuation lifecycle. Only the exact same complete selection can reuse its reservation without another daily admission charge. A changed selection needs separate admission; parent and sibling selections cannot borrow the reservation.

Each deployment must apply the capacity migrations and run matching runtime, coordinator, and recovery components. Verify concurrent admission, descendant cancellation and drain, and restart recovery in that deployment before relying on its capacity guarantees.

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 successful assignment, committed capacity counters increment under the persisted hard gate. Selecting workflows also reserve their full slate before exposing output or starting selected bodies, as described above.

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