POST /api/v1/tasks/:task_id/cancel

Cancel Task

Cancel a pending task. Only tasks with status pending can be cancelled.

Request

curl -X POST https://your-instance/api/v1/tasks/a1b2c3d4-.../cancel \
  -H "Authorization: Bearer htk_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Deployment rolled back" }'

Required scope: tasks:create

Request Body

Field	Type	Required	Description
`reason`	string	No	Cancellation reason (visible to operators)

Response

{
	"task_id": "a1b2c3d4-...",
	"status": "cancelled"
}

Errors

Status	Meaning
`401`	Missing or invalid token
`403`	Token lacks `tasks:create` scope
`404`	Task not found or belongs to a different organization
`409`	Task is not pending (already completed, cancelled, or failed)

Side Effects

When a task is cancelled:

The task status changes to cancelled immediately
Operators see the task move from Pending to Done
Configured webhook/NATS sinks receive a task.cancelled event
If linked to a process, the process step is NOT auto-updated (handle this in your process logic)