POST /api/external-tasks/claim

Lease parked external tasks to a worker (FIFO by park time); the returned token is the only handle accepted while the claim is live

Requires the worker permission (or admin).

Request

{
  "worker_id": "worker-1",
  "limit": 5,
  "lease_ms": 30000,
  "process": "expense-approval"
}

Response

{
  "items": [
    {
      "token": "550e8400-e29b-41d4-a716-446655440000.6.1",
      "process": "expense-approval",
      "version": 2,
      "task": "approval",
      "external_input": {
        "amount": 420,
        "submitter": "alice"
      },
      "result_schema": {
        "type": "object",
        "properties": {
          "approved": {
            "type": "boolean"
          }
        },
        "required": [
          "approved"
        ]
      },
      "raises": {
        "over_budget": null
      },
      "waiting_since": "2026-09-25T09:12:00Z",
      "deadline": "2026-09-26T09:12:00Z",
      "claimed_by": "worker-1",
      "claim_expires": "2026-09-25T09:30:30Z"
    }
  ],
  "renew_before_ms": 10000
}

Fails with 400, 500.

POST /api/external-tasks/renew

Extend this worker’s claims. Answers per token: renewed is still yours, lost is already someone else’s (stop, do not release), cancelled is yours but no longer wanted (stop and release). Renewal is mandatory, not an optimisation — it is the only channel that reaches a running worker

Requires the worker permission (or admin).

Request

{
  "worker_id": "worker-1",
  "tokens": [
    "550e8400-e29b-41d4-a716-446655440000.6.1"
  ],
  "lease_ms": 30000
}

Response

{
  "cancelled": [],
  "lost": [],
  "renew_before_ms": 10000,
  "renewed": [
    "550e8400-e29b-41d4-a716-446655440000.6.1"
  ]
}

Fails with 400, 500.

POST /api/external-tasks/release

Hand a claim back to the queue immediately instead of waiting out its lease

Requires the worker permission (or admin).

Request

{
  "token": "550e8400-e29b-41d4-a716-446655440000.6.1"
}

Response

{
  "released": true
}

Fails with 400, 409, 500.

POST /api/external-tasks/resolve

Submit an outcome for a waiting external task — a result, or an error routed through the task’s on_error rules; validated against what the task declares, then the process resumes

Requires the worker permission (or admin).

Request

{
  "token": "550e8400-e29b-41d4-a716-446655440000.6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "result": {
    "approved": true
  }
}

Response

{
  "resolved": true
}

Fails with 400, 404, 409, 500.

POST /api/external-tasks/signal

Deliver an outcome (result or error) to an external task by instance id + task id: resolves it if armed now, else buffers FIFO until the task next arms

Requires the worker permission (or admin).

Request

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "approval",
  "result": {
    "approved": true
  }
}

Response

{
  "buffered": false,
  "delivered": true
}

Fails with 400, 404, 409, 500.