---
title: "Update plan step status(es) or replace the full plan"
method: PATCH
path: "/tasks/{taskId}/plan"
tags: ["Tasks"]
---

# Update plan step status(es) or replace the full plan

`PATCH /tasks/{taskId}/plan`

## Request

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

## Path parameters

- `taskId` string, required

## Request body

- UpdateTaskPlanDto
  - `waitingOn` TaskWaitingOnDto
    - `kind` 'user' | 'agent', required: Whether the answer has to come from a person or an agent.
    - `id` string, required: Who was asked.
  - `stepId` string: Single-step form: the step to update. Pair with `status`.
  - `status` 'pending' | 'in_progress' | 'completed' | 'skipped'
  - `result` object: Whatever the step produced. Stored as-is on the step.
  - `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.
  - `steps` TaskPlanStepDto[]: Full-replace form: the new plan. Not valid with `stepId` or `patches`.
    - `stepId` string: Caller-chosen id, unique within the plan. Omit to let the server assign a stable `step-<n>` id from the array position.
    - `description` string, required: What this step does, in one line. Required and non-blank: this is the label whoever is watching progress reads before any step closes, so a blank one renders an unnamed row. Send the text when you know it rather than reserving a slot to fill in later.
    - `order` number: Position in the plan, ascending. Omit to use the step’s index in `steps`.
    - `status` 'pending' | 'in_progress' | 'completed' | 'skipped': Step progress. Omit for `pending`. On a full replace, send `completed` (or `in_progress`) for work already done so a later task completion does not rewrite finished steps as skipped.
    - `result` object: Optional step output stored with this replace.
    - `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.
  - `patches` TaskPlanStepPatchDto[]: Named-step progress. Only the listed steps change; the rest of the plan is untouched. Not valid with `steps` or the single-step form.
    - `stepId` string, required: Stable id of the step to change. Must already exist on the plan.
    - `status` 'pending' | 'in_progress' | 'completed' | 'skipped', required
    - `result` object: Whatever the step produced. Stored as-is on the step.
    - `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.

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