Stop work item

Request or confirm stop for a self-hosted work item.

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

Stops a work item. The request body is optional; an empty body or {} sends the default force=false request, also called a graceful stop.

For starting or active items, force=false moves the item to stopping. The worker should drain the in-flight work, then call this endpoint again to confirm completion and move the item to stopped. force=true moves any live item directly to stopped.

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
Content-Type	No	application/json when a body is sent

Request body

Field	Type	Required	Default	Description
force	boolean	No	false	If true, force the item to stopped without graceful drain

Example request: force=false

curl -X POST "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/work_019f3be4fd2475d9a784bf2c739e1194/stop" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

Example request: force=true

curl -X POST "https://api.qoder.com/api/v1/cloud/environments/env_019e64e01a137caf953ac2ac7b42ec5c/work/work_019f3be4fd2475d9a784bf2c739e1194/stop" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Example response

HTTP 200 OK

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

Response fields

Returns the updated Work item object.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Request body is not valid JSON
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

See Errors for the full error envelope.

State transitions

force=false means an empty body, {}, or {"force": false}. force=true means {"force": true}.

force	Current state	Result
false	queued	stopped
false	starting or active	stopping
false	stopping	stopped
false	stopped	Returns the existing stopped item
true	Any live state	stopped

Related

Cloud environment setup

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