Managing Resources

Everything Ductor routes, runs, and dispatches is a resource you manage through the API. These are the resources that shape the clearing surface: pools are the markets Work enters, recipients are the Workers a decision selects, and rules, workflows, publishers, and connections define how work is priced, routed, and delivered. The dashboard is optional — all of them are created, updated, inspected, and retired over the same REST + Connect-RPC surface your application already calls. This section is the operator's reference for that surface — what each resource is, why and when you manage it, how to do it with real API calls, and where it lives (endpoint, aggregate, storage).

The resource map

Each resource has its own page. Read them in roughly this order — later resources reference earlier ones.

Two API generations: /api and /api/v2

Ductor's REST surface is generated from the same protobuf definitions as the Connect-RPC API, so every operation exists in both dialects. As the platform grew, newer services were introduced under a /api/v2 prefix while the established resource CRUD kept its /api paths. Both are current and supported — the prefix simply tells you which generation a service belongs to.

Authentication and tenancy on every call

Every management endpoint is authenticated and tenant-scoped. Two things travel with each request:

• Authorization: Bearer <token> — a JWT from your OIDC provider, or a Ductor API key as the fallback credential.
• X-Tenant-ID: <uuid> — the tenant the call operates within.

export DUCTOR_API_KEY="duk_live_..."
export DUCTOR_TENANT="9c8b7a6d-1234-4e5f-8a9b-0c1d2e3f4a5b"

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

Authorization: resource + action + roles

Each RPC declares its own authorization requirement. The interceptor chain evaluates three things against your token:

• resource_type — what kind of object the call touches (pool, recipient, rule, workflow, workflow_run, workflow_definition, connector, tenant, config, …).
• action — read, write, delete, or admin.
• roles — an any-of role gate on sensitive operations. Ductor's built-in roles are viewer, operator, admin, and service. Tenant provisioning and API-key minting, for example, require admin.

Each resource page lists the exact resource_type:action (and any role gate) for its operations so you can scope keys to least privilege.

Conventions shared across every resource

Pagination

List endpoints take a pagination object and return a cursor. Page size caps at 1000, defaults to 50.

# First page
curl -s "https://api.ductor.io/api/pools?pagination.page_size=25" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

# Next page — feed back the token you were handed
curl -s "https://api.ductor.io/api/pools?pagination.page_size=25&pagination.page_token=eyJvZmZzZXQiOjI1fQ==" \
  -H "Authorization: Bearer $DUCTOR_API_KEY" -H "X-Tenant-ID: $DUCTOR_TENANT"

Every list response carries a pagination block:

{
  "pagination": {
    "next_page_token": "eyJvZmZzZXQiOjUwfQ==",
    "total_count": 250
  }
}

next_page_token is an opaque cursor — treat it as a blob, don't parse it. It's empty on the last page. total_count may be -1 when the total is too expensive to compute.

Response metadata

Every response — success or list — includes a metadata object for observability:

{
  "metadata": {
    "trace_id": "trace-abc123def456",
    "request_id": "req-789ghi012",
    "fetched_at": "2026-07-11T10:30:00Z"
  }
}

trace_id is the OpenTelemetry trace ID — quote it in a support ticket and the whole request is reconstructable end to end.

Errors are Problem JSON

REST errors follow RFC 9457 Problem Details. Domain sentinels map to stable HTTP statuses, and field-level validation failures are itemized:

{
  "type": "https://ductor.io/errors/validation",
  "title": "Invalid argument",
  "status": 400,
  "detail": "name: must not be empty",
  "errors": [
    { "field": "name", "description": "must not be empty", "reason": "FIELD_VIOLATION" }
  ]
}

The Connect-RPC surface returns the equivalent Connect/gRPC codes for the same sentinels.

Optimistic concurrency

Mutable resources that a coordinator or multiple operators can touch carry a version counter (record_version on pools, draft_revision on workflow drafts, db_record_version on workflow runs). Where an operation accepts an expected_version, the server rejects the write with 412 Failed Precondition if the stored version has moved on — you re-read, reconcile, and retry. This is the same optimistic-locking discipline the coordinator uses internally; see Optimistic Locking.

Where to start

If you're standing up a tenant from scratch, the path is linear: