Skip to main content

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: tasks you pinned first, then unfinished before finished, then most recently updated, with filters for state, board section, project, feature, persona, creator, assignee, origin (`source`), update window and text search. Pages by keyset: pass the `X-Next-Cursor` response header as `after` to continue; a `done` row's `release` names the furthest release that shipped it (`id`, `version`, empty until the release is pinned, `stage` and `arrived_at`), or is null when no release carried it. 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`, or started at once when the project's pipeline starts new tasks by itself. With no `persona`, it takes the New-task default the console's form would (an Epic default, else the project's default persona, else the organization's); `epic` 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 the created task with status 201.

๐Ÿ“„๏ธGet task page

Returns everything the task page shows in one response: `task` is the task as its own endpoint returns it, and `activity`, `artifacts`, `run_metrics`, `rating`, `comments`, `body_versions`, `dependencies`, `compliance_manifest`, `control_messages` and `live_cast` are each exactly what that panel's own endpoint returns; `trail` holds the task's `project_name` and `feature_name` (null for a task filed in the project itself). A panel its own endpoint would refuse you, or one that fails to load, is left out; request it there for the reason.

๐Ÿ“„๏ธReset task

Returns a task to a clean `draft` without running it: stops its agent, discards its worktree's changes and frees the worktree; resetting an epic resets the unarchived tasks under it as well, and returns 409 when nothing was reset, such as a task already in `draft`. What the attempt produced (question rounds and their answers, the report and other artifacts, the activity history) stays shown unless the optional body sets `delete_artifacts` to `true`, which hides it; the task's body, attachments, tags and dependencies are kept either way. 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 for a non-epic task `run_requested` runs it past unmet prerequisites and an epic that holds between stages. An operator acting as the organization may pass `push_as_id`, a project member who may start tasks, to push with that member's git account; a task with a repository and nobody to push as returns 422, and when the project's release pipeline needs approval to start, it returns 202 with `state` `waiting` and the task stays in `draft` until the approval lands; a caller not allowed to take that step gets 403 `step_forbidden`. `without_repo` runs the task, or every task in an epic's group, in an empty folder without the project's repository, for a starter who cannot read it (ignored on a project with no repository; 409 while one of them still holds a copy of the repository, or when no node of the project can run a task without it), and `fresh_elsewhere` gives up a non-epic task's MicroVM to start it again on another node (409 when it has no MicroVM or its project no other node).