Worker API

Registers a worker instance and returns a workerId used in subsequent heartbeat and job poll calls. Workers should call this on startup and re-register on restart.

Request body

Field	Type	Required	Description
workerName	string	required	Human-readable name for this worker instance (e.g. payment-worker-01).
jobTypes	string[]	required	List of task definition types this worker can handle.
maxJobsActive	integer	optional	Max concurrent jobs. Defaults to 32.

Example request

{
  "workerName": "payment-worker-01",
  "jobTypes": ["payment:charge", "payment:refund"],
  "maxJobsActive": 10
}

Example response 200 OK

{
  "workerId": "wrk_abc123",
  "registeredAt": "2026-04-06T09:00:00Z"
}

Workers must send a heartbeat every 30 seconds. Workers that miss 3 consecutive heartbeats are marked inactive and their in-progress job locks are released.

Request body

Field	Type	Required	Description
workerId	string	required	Worker ID from the registration response.
jobsActive	integer	optional	Current number of active jobs being processed.

Example request

{ "workerId": "wrk_abc123", "jobsActive": 3 }

Response 204 No Content

Atomically locks and returns up to maxJobsToActivate jobs matching the given job types. Jobs remain locked for the duration of timeout milliseconds.

Request body

Field	Type	Required	Description
workerId	string	required	Your worker's ID.
jobType	string	required	Task definition type to poll for.
maxJobsToActivate	integer	optional	Max jobs to return. Defaults to 1.
timeout	integer	optional	Lock duration in milliseconds. Defaults to 30 000.
variables	string[]	optional	Variable names to fetch with the job. Omit for all variables.

Example request

{
  "workerId": "wrk_abc123",
  "jobType": "payment:charge",
  "maxJobsToActivate": 5,
  "timeout": 60000,
  "variables": ["orderId", "amount", "currency"]
}

Example response 200 OK

{
  "jobs": [
    {
      "key": "job_xyz789",
      "type": "payment:charge",
      "processInstanceKey": "pi_111",
      "variables": { "orderId": "ORD-42", "amount": 9900, "currency": "EUR" },
      "deadline": "2026-04-06T09:01:00Z"
    }
  ]
}

Marks a job as successfully completed. Optionally merges output variables back into the process instance. The process engine resumes from the next step.

Request body

Field	Type	Required	Description
variables	object	optional	Output variables to merge into the process instance scope.

Example request

{ "variables": { "chargeId": "ch_stripe_abc", "status": "succeeded" } }

Response 204 No Content

Marks a job as failed. Set retries to control how many more attempts are allowed. When retries reach 0, an incident is raised.

Request body

Field	Type	Required	Description
retries	integer	required	Remaining retries. Set to 0 to create an incident immediately.
errorMessage	string	optional	Human-readable failure reason, shown in the incident.
retryBackoff	integer	optional	Milliseconds to wait before the job becomes available again.

Example request

{ "retries": 2, "errorMessage": "Stripe timeout", "retryBackoff": 5000 }

Response 204 No Content

Returns all currently registered workers and their status.

Example response 200 OK

{
  "workers": [
    {
      "workerId": "wrk_abc123",
      "workerName": "payment-worker-01",
      "jobTypes": ["payment:charge"],
      "status": "active",
      "lastHeartbeat": "2026-04-06T09:00:55Z"
    }
  ]
}