Tasks

Tasks are the unit of work an agent runs: create, edit, start, pause and complete them, and follow their comments, questions, attachments and dependencies. An epic is a task that groups child tasks into a pipeline.

📄️List tasks

Lists top-level tasks the caller may see, unfinished first, then most recently updated, with filters for state, project, feature, persona, creator, update window and text search. Pages by keyset: pass the `X-Next-Cursor` response header as `after` to continue. With `parent_id`, returns that task's visible, unarchived children instead and ignores the other filters.

📄️Create task

Creates a top-level task in `draft`. The default `persona` is `epic`, which also creates its analysis, architecture and plan children, and a multi-stage `playbook_id` creates the playbook's stages; another creatable persona creates one task. Returns 400 when the project has dispatch turned off and 403 for an `advisor` chat without edit permission on the project's worktrees, else the created task with status 201.

📄️Get task counts

Returns counts per board section (in progress, stopped, draft, done), with stopped split into questions, waiting, paused and failed, plus a total, for the same top-level tasks the task list returns under the same filters. Paging and section parameters are ignored, since counts cover the whole set.

📄️List task creators

Lists each person who created top-level tasks the caller may see, with their task count, ordered by count. Use the returned `id` as the `created_by_id` filter on the task list. The current user is always included.

📄️List task models

Lists the models a task may be pinned to, most capable first. Each entry has a `value`, a `label` and a `description`.

📄️List task personas

Returns every task persona in display order, with its label, hints and which states settle it, plus the picker hint text. Includes system personas; `operator_pickable` marks the ones a person may choose.

📄️Get task queue

Returns the tasks running now and the tasks waiting to run, in the order they will be dispatched. Each queued task states whether it can be dispatched and, if not, why. Hidden, archived and epic tasks are excluded.

📄️Get task tag counts

Returns the number of top-level tasks carrying each tag of every active tag group, plus an `untagged` count, under the task list's project, feature, creator, focus, update window, hidden and archived filters. Tags with no tasks are reported as 0.

📄️Get task tree

Returns the caller's task navigation tree in one response: each visible project, its features and unfiled tasks, with task counts on every node and parent counts summed from their children.

📄️Delete task

Deletes a task and all of its children, stopping any of their runs and freeing their worktrees. Refused with 409 while the task is `ready`, `active` or `awaiting_response`. Returns 204 with no body.

📄️Get task

Returns one task in full, including its children when it has any, its question-and-answer history and its latest stage output.

📄️Set task priority

Sets a task's `priority`, which orders the dispatch queue: higher runs sooner, negative runs later than normal. Allowed in any state and idempotent. Returns the updated task.

📄️Update task

Updates a task's fields in any state; a running task picks up title and description edits on its next run, and changing `persona` reconciles its children. Moving a task to another project returns 400 while any task in its subtree is queued, running or awaiting an answer; a stopped task moves, and the worktree it held is released. Returns the updated task.

📄️Get task activity

Returns the task's activity log in time order: its state changes and notes, including those of its direct children. Each run phase carries its duration, still counting while the phase is open.

📄️Answer a task's open question

Answers the question a task in `awaiting_response` is waiting on: a live run receives the answer directly, otherwise the task goes back to the queue. When the task has open question rounds, resolves the one named by `question_id` or else the oldest. Returns the updated task; a chat task or any other state returns 409.

📄️Answer question

Answers one open question round on a task, the named one or else the oldest, with free text or the offered choices. The run resumes once no round remains open. Returns the updated task.

📄️List artifacts

Lists the documents the agent produced for this task, newest first, as metadata only. Superseded versions stay listed with `current` set to false.

📄️Get artifact content

Returns the content of one task artifact for display in place. Pass `download=true` to receive it as a file download instead.

📄️List attachments

Lists the files people attached to this task as inputs, oldest first. Agent output is not included; list it with the artifacts endpoint.

📄️Upload attachment

Uploads one file to the task as an input attachment, sent as a multipart form. Call once per file. Returns the stored attachment with status 201, or 409 when the task or your organization has reached its attachment storage limit.

📄️Create attachment ticket

Starts a direct upload of one attachment: declare the file name, type and size, and receive an attachment `id` and an `upload_url` to PUT the bytes to. Oversized files are refused here, and so is a file past the task's or your organization's attachment storage limit (409). Confirm the upload afterwards to make the attachment visible.

📄️Delete attachment

Removes one input attachment from the task and deletes its stored file. Agent output cannot be removed this way. Returns 204 with no body.

📄️Confirm attachment

Completes a direct attachment upload once the bytes are stored, recording the received size and making the attachment visible on the task. Returns the attachment.

📄️Get task attachment content

Redirects to a short-lived download link for one task attachment or comment image. Agent output from a run that was reset is not returned.

📄️List body versions

Lists the previous descriptions of a task, newest first, each with when and how it was saved.

📄️Create comment image ticket

Starts a direct upload of one image for a comment not yet posted, returning an attachment `id` and an `upload_url` for the bytes. Raster images only, within a size cap and the attachment storage limit (409). The image attaches to the comment that later includes it.

📄️Confirm comment image

Completes a comment image upload once the bytes are stored. Only the person who started the upload may confirm it. Returns the image attachment.

📄️List comments

Lists the task's most recent comments, up to `limit` (default 200, at most 500), in chronological order, with their mentions, images and reactions.

📄️Create comment

Posts a comment on the task and notifies the people it mentions with @. Requires edit access to the task. Returns the created comment with status 201.

📄️Delete comment

Deletes a comment with its mentions, images and reactions. Authors may delete their own; deleting another person's comment requires delete access to the task. Returns 204 with no body.

📄️Update comment

Edits the text of a comment and notifies newly mentioned people. Only its author may edit it; anyone else gets 403. Returns the updated comment.

📄️Remove reaction

Removes the current user's emoji reaction from a comment. Idempotent. Returns the comment.

📄️Add reaction

Adds the current user's emoji reaction, from a fixed set, to a comment; the author is notified of each person's first reaction. Idempotent. Returns the comment.

📄️Complete task

Marks a task `done` by hand from any state except `done`, which returns 409; an epic's children are not affected. An optional body records an outcome summary and a pull request link. Returns the updated task.

📄️Get task dependencies

Returns a task's prerequisites, the tasks that depend on it, and whether it is ready to run. Tasks the caller cannot see are left out of the lists; hidden unmet prerequisites and hidden dependents are reported only as counts.

📄️Add task dependency

Makes the task wait for the task given as `depends_on_task_id`, from the next dispatch on. Self-references, cycles and deadlocks return 422; adding an existing link is a no-op. Returns the updated dependencies.

📄️Remove task dependency

Removes one prerequisite from a task, which may let it run. Returns 204 with no body whether or not the link existed.

📄️Get dispatch forecast

Reports whether the task would run now if marked ready and, if not, the reasons and its queue position. Also lists running tasks that could be stopped to make room.

📄️Force start task

Starts the task right away by stopping the running task named in `stop_task_id` and putting that one back in the queue, raising this task's priority above it if needed. Returns 409 when this task is an epic or already active, or the named task is not running. Returns the started task.

📄️Ignore question

Dismisses one open question round without answering it, the named one or else the oldest; the agent is told it was declined. Returns the updated task.

📄️List mention candidates

Lists the people who may be mentioned in this task's comments, alphabetically, with their `id` and `name`.

📄️List task questions

Lists the task's questions, oldest first. Returns open questions by default; pass `status` with another value to filter, or empty for all. Each carries its round number across the full history.

📄️Get task rating

Returns the task's star rating: the average and count, the current user's own vote, and each voter's stars.

📄️Rate task

Records the current user's 1 to 5 star vote on a finished top-level task or epic, replacing any earlier vote. Returns 409 if the task is not rateable or not yet `done`. Returns the updated rating.

📄️Reset task

Returns a task to a clean `draft` from any other state without running it: stops its agent, discards its work and frees its worktree. Epics are refused with 400. Returns the updated task.

📄️Retag task

Reclassifies the task automatically and replaces its tags in every active tag group. Nothing changes if classification fails. Returns the resulting tags.

📄️Revise question

Reopens one already answered or dismissed question round, named by `question_id`, so it can be answered again. Returns the updated task.

📄️Get task run metrics

Returns total run time, agent time, input and output usage and cost for the task and all of its descendants, plus the model that ran. Works for unfinished tasks too.

📄️Set task state

Moves a task to any state, or to waiting on the customer with an optional note, stopping a running task first where the move needs it. Setting `active` or `awaiting_response` changes only the state and starts no run, setting `ready` on an epic starts it so it ends up `active`, and setting the current state only clears a waiting mark. Returns the updated task.

📄️Start task

Starts a task: queues it for dispatch, or starts or reactivates an epic's pipeline. An `active` task is left unchanged, an `awaiting_response` task returns 409, and a project with dispatch turned off returns 400. For a non-epic task, `run_requested` runs it past unmet prerequisites and an epic that holds between stages; it is ignored for an epic.