Skip to main content
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

ParameterTypeDescription
environment_idstringEnvironment ID with the env_ prefix
work_idstringWork item ID with the work_ prefix

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer $QODER_PAT
Worker-IDNoStable 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

HTTPTypeTrigger
400invalid_request_errorThe Environment is not self_hosted
401authentication_errorPAT invalid or expired
403permission_errorNot authorized for this operation
404not_found_errorEnvironment or work item not found
409invalid_request_errorWork 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.