> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

```bash theme={null}
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`

```bash theme={null}
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**

```json theme={null}
{
  "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](/cloud-agents/api/environments/work/schemas#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](/cloud-agents/api/conventions/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

<CardGroup cols={2}>
  <Card title="Cloud environment setup" icon="server" href="/cloud-agents/environments">
    Choose the container, network, and dependencies your agent runs in.
  </Card>
</CardGroup>