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

# POST /api/v1/tasks/{id}/cancel

> Cancel a queued or running task (idempotent)

## Endpoint

```
POST http://localhost:8080/api/v1/tasks/{id}/cancel
```

## Description

Cancels a queued or running task. Returns `202 Accepted` when the cancellation is accepted for processing. If the task has already reached a terminal state, returns `409 Conflict`.

## Authentication

**Required**: Yes

Include API key in header:

```
X-API-Key: sk_test_123456
```

## Request

### Headers

| Header         | Required | Description                         |
| -------------- | -------- | ----------------------------------- |
| `X-API-Key`    | Yes      | API authentication key              |
| `Content-Type` | No       | `application/json` if body provided |
| `traceparent`  | No       | W3C trace context                   |

### Path Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `id`      | string | Yes      | Task ID (Temporal workflow ID) |

### Body Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `reason`  | string | No       | Optional human-readable reason |

### Request Body Schema

```json theme={null}
{
  "reason": "Stopped by user"
}
```

## Response

### 202 Accepted

```json theme={null}
{
  "success": true,
  "message": "Task cancelled successfully"
}
```

### 409 Conflict

```json theme={null}
{
  "success": false,
  "message": "Task is already in terminal state: COMPLETED",
  "status": "COMPLETED"
}
```

### 404 Not Found

```json theme={null}
{ "error": "Task not found" }
```

### 401 / 403

```json theme={null}
{ "error": "Unauthorized" }
```

or

```json theme={null}
{ "error": "Forbidden" }
```

## Examples

### curl

```bash theme={null}
curl -X POST "http://localhost:8080/api/v1/tasks/${TASK_ID}/cancel" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"user request"}'
```

### Python (httpx)

```python theme={null}
import httpx

resp = httpx.post(
    f"http://localhost:8080/api/v1/tasks/{task_id}/cancel",
    headers={"X-API-Key": api_key},
    json={"reason": "cleanup"}
)
print(resp.status_code, resp.json())
```

### JavaScript (axios)

```javascript theme={null}
await axios.post(
  `http://localhost:8080/api/v1/tasks/${taskId}/cancel`,
  { reason: "not needed" },
  { headers: { "X-API-Key": apiKey } }
);
```

## Notes

* Idempotent: repeated calls return `202` or `409` depending on current state.
* Cancellation is propagated to child workflows (graceful via `REQUEST_CANCEL`).