genroc

    docs / Reference / REST API

    External Tasks

    The 5 HTTP endpoints under External Tasks.

    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",
      "task": "approval"
    }

    Response

    {
      "items": [
        {
          "token": "5fy765kh.6.1",
          "process": "expense-approval",
          "version": 2,
          "task": "approval",
          "external_input": {
            "amount": 420,
            "submitter": "alice"
          },
          "waiting_since": "2026-09-25T09:12:00Z",
          "deadline": "2026-09-26T09:12:00Z"
        }
      ]
    }

    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 no longer wanted (stop; nothing to release). Optional, but the only channel that tells a running worker to stop

    Requires the worker permission (or admin).

    Request

    {
      "worker_id": "worker-1",
      "tokens": [
        "5fy765kh.6.1"
      ],
      "lease_ms": 30000
    }

    Response

    {
      "cancelled": [],
      "lost": [],
      "renewed": [
        "5fy765kh.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": "5fy765kh.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": "5fy765kh.6.1",
      "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": "5fy765kh",
      "task": "approval",
      "result": {
        "approved": true
      }
    }

    Response

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

    Fails with 400, 404, 409, 500.