Acknowledge work item

Acknowledge a delivered work item before executing it.

POST /api/v1/cloud/environments/{environment_id}/work/{work_id}/ack

Acknowledges a delivered work item and moves it from queued to starting. Workers should ack after poll and before executing the Session work.

Ack is safe to retry for items already in starting or active. It conflicts for stopping or stopped items.

Path parameters

Parameter	Type	Description
environment_id	string	Environment ID with the env_ prefix
work_id	string	Work item ID with the work_ prefix

Headers

Header	Required	Description
Authorization	Yes	Bearer $QODER_PAT
Worker-ID	No	Stable worker identity. If poll stored a different Worker-ID, ack returns 409

Example request

curl -X POST "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/work_019f3be4fd2475d9a784bf2c739e1194/ack" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Worker-ID: byoc-worker-01"

Example response

HTTP 200 OK

{
  "id": "work_019f3be4fd2475d9a784bf2c739e1194",
  "type": "work",
  "environment_id": "env_019e64e01a137caf953ac2ac7b42ec5c",
  "data": {
    "type": "session",
    "id": "sess_019f3be3fa66750bb9a1fbcde85b5fe1"
  },
  "state": "starting",
  "created_at": "2026-07-01T08:15:01Z",
  "acknowledged_at": "2026-07-01T08:15:04Z",
  "started_at": null,
  "latest_heartbeat_at": null,
  "stop_requested_at": null,
  "stopped_at": null,
  "metadata": {}
}

Response fields

Returns the acknowledged Work item object.

Errors

HTTP	Type	Trigger
400	invalid_request_error	The Environment is not self_hosted
401	authentication_error	PAT invalid or expired
403	permission_error	Not authorized for this operation
404	not_found_error	Environment or work item not found
409	invalid_request_error	Work item was claimed by another worker, changed state concurrently, or is stopping/stopped

See Errors for the full error envelope.

Notes

• After ack, the first heartbeat usually uses expected_last_heartbeat=NO_HEARTBEAT.
• Ack triggers an immediate dispatch pass so work can proceed without waiting for the next dispatcher tick.

Related

Cloud environment setup

Choose the container, network, and dependencies your agent runs in.