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.
List task assignees
Lists each person assigned top-level tasks the caller may see, with their task count, ordered by count. Use the returned `id` as the `assigned_to_id` filter on the task list. The current user is always included.
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 creator of top-level tasks the caller may see, with their task count, ordered by count, with one System entry for tasks no person created. 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.
List task sources
Lists every origin a task can have, in display order. Each entry has a `value`, which the task list's `source` filter takes, and a readable `label`.
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, origin, state, persona, 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 the tasks filed in the project itself, 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, freeing their worktrees and erasing their signed compliance manifests. 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; on an epic it also sets every sub-task that is not done or archived. Allowed in any state and idempotent. Returns the updated task.
Update task
Updates a task's fields in any state: a save that changes `body`, `autonomous` or the model pin reaches a running task at once, a `title` edit applies 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 one open question round on a task in `awaiting_response`, the one named by `question_id` or else the oldest. The run resumes once no round remains open. Returns the updated task; any other state, or no open round, 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 file; a comment file of a PNG, JPEG, GIF or WebP type opens in place, any other downloads. 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 file of any type for a comment not yet posted, returning an attachment `id` and an `upload_url` for the bytes. A file over 10 MB returns 413, and one past the task's or your organization's attachment storage limit returns 409. The file attaches to the comment that later includes it: a PNG, JPEG, GIF or WebP file shows as a picture, any other file as a download.
Confirm comment image
Completes a comment file upload once the bytes are stored. Only the person who started the upload may confirm it; for anyone else it returns 404. Returns the attachment.
List comments
Lists the task's most recent comments, up to `limit` (default 200, at most 500), in chronological order, with their mentions, files (`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, files 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 compliance manifest
Returns the task's signed compliance manifest status: `state` is `not_done`, `not_sealed`, `waiting`, `sealing`, `sealed` or `failed`, with a readable `detail`, every version newest first (a failed one carries its reason and no download links), and `newer_data_available` when a session transcript has landed since the latest seal. Requires permission to view the task.
Regenerate compliance manifest
Seals a new version of a done task's compliance manifest; earlier versions stay downloadable and verifiable. Returns 409 when the task is not done or a seal is already in progress, and 503 when seal status cannot be read. Requires permission to edit the task; returns the expected version with status 202.
Download compliance manifest html
Redirects (302) to a short-lived download of one sealed version's readable rendering, named `jaah-manifest-task-<id>-v<N>.html`. Returns 404 for a version that is not sealed. Requires permission to view the task.
Download compliance manifest JSON
Redirects (302) to a short-lived download of one sealed version's signed manifest, named `jaah-manifest-task-<id>-v<N>.json`. Returns 404 for a version that is not sealed. Requires permission to view the task.
List control messages
Lists what the control plane typed into the task's live runner and the operator answers it delivered. It returns the 200 most recent, oldest first, each with its time, sender, text, and whether it was delivered or dropped.
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; `push_as_id` is as on `start_task`. Returns 409 when this task is an epic or already active, or the named task is not running, else 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.
Answer input requests
Answers or skips several open question rounds in one call, each named by its id. Each entry is saved or refused on its own, and the run resumes once, when no round remains open. Returns the updated task and, per entry in the order sent, whether it was answered, dismissed or failed with the reason.
Answer input request
Answers the question round named in the path, with free text or the offered choices. The run resumes once no round remains open. Returns the updated task; a body naming a different round returns 422.
List a task's merge-lane stage timings
Returns the merge-lane gate runs whose tested tree held one of the task's PRs, newest first (at most 10): each with its lane task, tree, `recorded_at`, the PRs it held and its `stages` in gate order, each with `stage`, `seconds` and `outcome` (`passed`, `failed` or `flaked`: passed on a retry).
Get task Live Cast state
Returns whether Live Cast is on for the task's project and, when it is, the task's effective state (`published` or `hidden`) and its source (`override`, `rules` or `pending`). Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
Set task Live Cast override
Sets a manual Live Cast override on the task (`published` or `hidden`), or clears it with `null`; an override stays until an admin clears it. Returns 409 when Live Cast is off for the project. Requires the Org Owner or Org Admin role; 403 when the plan has no Live Cast.
List mention candidates
Lists the people who may be mentioned in this task's comments, alphabetically, with their `id` and `name`.
Add caused by link
Records that this task fixes a defect another task's merged work caused, named by `origin_task_id` or by the `pr_url` that merged it. The link is confirmed at once and moves the origin to `fixed_forward`; an origin with no merged work returns 404. Requires the Org Owner or Org Admin role.
Get a task's outcomes
Returns the task's outcome ledger rows, one per dispatch, each with its pushed heads and its defect links, and `can_decide`: whether you may confirm or dismiss a link.
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.
List question drafts
Lists the current user's unsent answers to the task's open questions, oldest first: the picked option indices, the note and the attached files. Read-only.
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.
Save question draft
Saves the current user's unsent answer to one open question: picked option indices, a note and attachment ids. An empty answer deletes it. Returns 409 once the question is answered or dismissed; nothing is sent to the agent.
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` 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.
Retag task
Reclassifies the task automatically and replaces its tags in every active tag group. Nothing changes if classification fails. Returns the resulting tags.
List a task's review findings
Returns what review lanes found in the task's change, most severe first: each finding's `severity`, `category`, `file` and `line`, `title`, `detail`, the lane that found it, and the detecting and authoring configuration as display names. Advisory: nothing blocks on a finding.
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 routing
Returns how the task's runner is chosen: `live` is the decision its next dispatch will use (null when there is none yet) and `history` every earlier dispatch's final decision, newest first. Each names the mode and why, a plain reason, the router's pick, the default, what actually ran and the candidates considered. Read-only.
Accept task routing
Accepts the router's recommendation for the task ('Use this'): its pick becomes the task's runner and model, as a person's choice, and the decision is recorded accepted. Requires permission to edit the task. 409 when there is no recommendation to accept: the project is not in Recommend mode, it was already answered, the task is dispatching, or the router fell back to the default.
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 and the peak memory, peak CPU and CPU time of the task's own sessions. Works for unfinished tasks too.
Mark task seen
Records that the current user opened the task, clearing its `done_unseen` mark for them until it ships again. Records nothing when the task's done notice is not owed to you. Returns 204 with no body.
Get task session usage
Returns each of the task's own sessions with its CPU and memory over the last `hours` (default 24) and its peak memory, peak CPU and CPU time. A task no session reported for returns an empty list.
Read session events
Reads an agent session's event stream on a task: messages, commands, file changes, tool calls, approvals, usage and errors, one shape for every engine. Returns events after the sequence number `after`; `more` says another page is ready. Requires permission to edit sessions.
Download session events
Downloads an agent session's whole event stream as JSON lines, one event per line. Returns 409 when the session has no event stream. Requires permission to edit sessions.
Set task state
Moves a task to any state, 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 changes nothing. 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).
Stop task
Stops a running or queued task and parks it in `paused`, keeping its worktree so a later start resumes it. Stopping an epic stops its unfinished children; stopping twice is harmless. Returns the updated task.
Replace tags
Replaces the task's tags with the given selection across every active tag group; a group left out is cleared, and an empty body clears all tags. Returns the resulting tags.
Rename task
Sets a task's title and nothing else. A platform operator may rename a task in another org this way. Returns the updated task.
Regenerate task title
Writes a new title for a task from its current description, replacing the stored one. Returns the updated task.