Acknowledge work item

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.

Cloud environment setup

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

​Path parameters

​Headers

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related