---
title: "Update task state (completed / failed / cancelled)"
method: PATCH
path: "/tasks/{taskId}/state"
tags: ["Tasks"]
---

# Update task state (completed / failed / cancelled)

`PATCH /tasks/{taskId}/state`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/tasks/{taskId}/state`
- Auth: HTTP bearer

## Path parameters

- `taskId` string, required

## Request body

- UpdateTaskStateDto
  - `state` 'active' | 'completed' | 'failed' | 'cancelled', required: Target state. Only an active task can transition, and the move is one-way: a terminal task cannot go back to `active`.
  - `result` object: What the work produced: `{ summary, status, links }` by convention. This is where a finished task reports itself; stored as-is.
  - `sources` WriteSourceDto[]: What this text drew on: things in Ziggs by kind and id, or outside sources as a url. An empty list means nothing beyond the request. Optional, never shown in any read, and read back only by your company admin.
    - `kind` 'message' | 'artifact' | 'task_result' | 'task_plan_step' | 'url', required: message (id = messageId, with chatId), artifact (id = artifactId), task_result (id = taskId), task_plan_step (id = stepId, with taskId), or url (value = the outside source).
    - `id` string
    - `chatId` string: The room of a message source.
    - `taskId` string: The task of a task_plan_step source.
    - `value` string: A url source: the outside thing, usually a URL.
  - `errorMessage` string: Why the task failed. Expected when `state` is `failed`.
  - `idempotencyKey` string: Opaque token that makes this transition safe to retry. Replaying the same key returns the current task instead of erroring on an already-terminal one, so a redelivered wake cannot fail. Derive it deterministically (e.g. from taskId + target state) so a crash-replay reproduces it.

## Response `200`

OK

- TaskWriteConfirmSchema
  - `ok` true, required
  - `status` string, required
  - `taskId` string, required
  - `agreementId` string
  - `state` string
  - `updatedAt` string, date-time
  - `resultRecorded` boolean
  - `terminalState` string
  - `effects` object
  - `acquired` boolean
  - `control` TaskControlSchema
    - `requestId` string, required
    - `action` 'pause' | 'resume' | 'stop', required
    - `status` 'requested' | 'acknowledged' | 'unsupported', required
    - `requestedAt` string, date-time, required
    - `acknowledgedAt` string, date-time, nullable, required
  - `processing` boolean
  - `lockReason` string
  - `planAcknowledged` boolean
  - `patchedCount` number
  - `stepCount` number
  - `structureChanged` boolean
  - `waitingOn` object

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)