Worker API

Base URL: your SDK-facing API, locally http://localhost:8081. Read authentication and conventions first. Download OpenAPI 3.0 for the full machine-readable contract.

POST /stages/{stageId}/lease/acquire

Acquire the lease for a dispatched stage execution

Worker protocol endpoint. The worker session token binds the lease to the authenticated worker session. acquired=false is a successful response indicating that the delivery must not execute the handler.

The current lease duration is 60 seconds. A repeated acquisition is not reentrant: an active Running execution returns lease_held, including when the caller previously acquired it. The application comes from the session.

Authentication: WorkerSessionAuth

Parameters

Request body

Required.

Content type: application/json. StageLeaseRequest

$ref: "#/components/schemas/StageLeaseRequest"

Responses

POST /stages/{stageId}/lease/renew

Renew the lease for a running stage execution

Worker-session endpoint. Renewal succeeds only for the current Running execution and lease owner while its lease remains unexpired. Success extends the execution lease by 60 seconds. It does not extend the HTTP delivery token's visibility timeout. On a definitive refusal, stop further handler side effects cooperatively. Server-side fencing and recovery determine which result applies.

Authentication: WorkerSessionAuth

Parameters

Request body

Required.

Content type: application/json. StageLeaseRequest

$ref: "#/components/schemas/StageLeaseRequest"

Responses

POST /jobs/pull

Pull the next stage job for a handler queue

HTTP gateway over the authenticated application's StageNext queues. Only the application API key is checked; worker-session validation occurs on lease and result operations. A queue outside this application's handler pattern is 403.

waitSeconds defaults to zero and accepts 0..20. A positive value polls roughly every 250 ms until a message arrives or the deadline produces 204.

A 200 response includes a process-local acknowledgement token. The delivery remains unacknowledged at the broker until acknowledged or requeued. Expiry sweeps attempt requeue after GATEWAY_VISIBILITY_TIMEOUT (default 60 seconds). Lease renewal does not extend that delivery timeout. GATEWAY_MAX_INFLIGHT defaults to 128 pending deliveries per API process; capacity exhaustion is 429.

Authentication: ApiKeyAuth

Request body

Required.

Content type: application/json. PullJobRequest

$ref: "#/components/schemas/PullJobRequest"

Responses

POST /jobs/ack

Acknowledge or requeue a pulled stage job

The opaque body token authorizes acknowledgement; this handler does not check an API key or worker session. Protect the token as a credential.

For executed work, send requeue:false only after the result endpoint returned 202. Stale or duplicate deliveries rejected by lease acquisition may be acknowledged without executing. requeue:true returns a delivery to the broker; it does not reset an execution lease or itself create a new execution attempt.

Tokens are held by the API process that performed the pull. Route pull and ack to the same instance. A 404 means that process does not hold the token: it may have expired, been acknowledged, or belong to another replica. A 404 does not prove that requeue succeeded. Repeated acknowledgement is not idempotent.

Authentication: No header security scheme; read the operation description for body credentials or delivery-token requirements.

Request body

Required.

Content type: application/json. AckJobRequest

$ref: "#/components/schemas/AckJobRequest"

Responses

POST /stages/{stageId}/result

Report a stage result over HTTP

Requires an application API key and a valid worker session for that application. Validates the stage's application ownership and message shape, then publishes persistently with broker confirms. A 202 means broker acceptance, not an applied database update. Stale or duplicate results may be accepted and later discarded by the asynchronous result consumer's execution-ID/attempt fencing.

The result string is limited to 262144 bytes; the complete JSON request body is limited to 327680 bytes. Unknown fields are accepted for SDK compatibility and ignored if the server message type does not recognize them. Acknowledge the original pulled delivery after 202. On an unknown result-posting outcome, retry the same computed result and execution identity rather than rerunning effects.

Authentication: ApiKeyAuth + WorkerSessionAuth

Parameters

Request body

Required.

Content type: application/json. StageResultSubmit

$ref: "#/components/schemas/StageResultSubmit"

Responses

POST /workers/bootstrap

Register a worker and receive its session

Register a worker using an application API key and receive its workerId and session token. Send X-Worker-Session to lease, result, heartbeat, events, and shutdown operations; result submission also requires X-API-Key. HTTP workers use jobs/pull and ignore messageBroker.connectionString.

WORKER_SESSION_TTL defaults to 24 hours. Heartbeats do not extend expiry. Rebootstrap of an existing application/instanceId reuses the worker record and replaces its token. Concurrent processes must use different instance IDs.

Authentication: ApiKeyAuth

Request body

Required.

Content type: application/json. WorkerBootstrapRequest

$ref: "#/components/schemas/WorkerBootstrapRequest"

Responses

POST /workers/heartbeat

Report worker liveness and counters

Records liveness and optional counters. Requires a valid, unexpired worker session matching workerId. Does not extend the session expiry.

Authentication: WorkerSessionAuth

Request body

Required.

Content type: application/json. WorkerHeartbeatRequest

$ref: "#/components/schemas/WorkerHeartbeatRequest"

Responses

POST /workers/events

Append worker lifecycle events

Batched, at most WORKER_EVENTS_MAX_BATCH events per call. Events feed the dashboard's worker activity feed and alerting.

Authentication: WorkerSessionAuth

Request body

Required.

Content type: application/json. WorkerEventsRequest

$ref: "#/components/schemas/WorkerEventsRequest"

Responses

POST /workers/shutdown

Announce a graceful shutdown

Marks the matching worker record stopped and records a lifecycle event. This is not token revocation; the handler matches workerId and the stored token but does not check session expiry.

Authentication: WorkerSessionAuth

Request body

Required.

Content type: application/json. WorkerShutdownRequest

$ref: "#/components/schemas/WorkerShutdownRequest"

Responses