Tasks
Tasks are your engineering backlog. Create, update and delete tasks, keep a log of progress on each, and have AI describe a task from its screenshots. A coding agent working on tasks in a session also reports here: when it starts, its plan, its progress, how it verified the work and the pull request it opened. See Tasks.
Begin work on tasks in the session
Atomic start-work transition for every task in the session: sets each task to in_progress, sets the parent feature to in_development (if not already), sets the containing session to in_progress (if not already). Pass taskIds in the body to operate on all tasks in the session; without it the server only starts the path :taskId. All taskIds must belong to the same session as the path :taskId. A session that is completed, cancelled or rolled back is not reopened: the call is refused (409) and nothing changes; create a new session for the task to start work on it.
path Parameters
workspaceIdWorkspace UUID
taskIdTask UUID
Begin work on tasks in the session › Request Body
taskIdsEvery task ID to start work on. If omitted, only the path :taskId is started. All taskIds must belong to the same session as the path :taskId.
Begin work on tasks in the session › Responses
Updated entities
Save the implementation plan
Saves the overall plan as a session log entry (a message in the conversation of the session containing this task), and saves per-task plan details as task log entries. It does NOT change the session description, the plan document the session page shows: to publish an approved plan there, call update-session-description. When the body includes taskIds, the server validates that every taskId has a corresponding entry in taskPlans and rejects the call on incomplete coverage: incomplete plans are scope drift.
path Parameters
workspaceIdWorkspace UUID
taskIdTask UUID
Save the implementation plan › Request Body
overallPlanMarkdown plan covering all tasks in the session. Stored as a session log entry, a message in the session conversation; it does NOT change the session description. Publish an approved plan there with update-session-description.
Per-task plan details. Each entry is stored as a task log on the corresponding task.
taskIdsTask IDs in the session. When provided, the server validates that taskPlans covers every id in this set (and only ids in this set). Pass the same taskIds you used for start-task-work.
Save the implementation plan › Responses
Plan saved
Report progress on a task
Adds a progress note as a task log entry and, when the task belongs to a session, posts it to that session's conversation, where the team follows the work. Call this per task at meaningful milestones: when you finish a sub-component, hit something unexpected, or switch to another task in the session. Skipped progress reports are an audit-trail bug.
path Parameters
workspaceIdWorkspace UUID
taskIdTask UUID
Report progress on a task › Request Body
contentProgress note, in markdown: what changed and where, anything unexpected, what comes next. Saved as a task log entry and, when the task is in a session, posted to the session's conversation.
attachmentIdsIDs of screenshots you uploaded to this session with request-attachment-upload (entity session). They show with this note in the session's conversation and in its snippets strip. Images uploaded to a task are not shown there.
Report progress on a task › Responses
Progress recorded
Save the verification summary
Records a verification summary as a session log entry on the session containing this task. When taskIds is provided, the same content is also written as a task log on every task in the set. Optionally references attachment IDs that were already uploaded to the session with request-attachment-upload (entity session).
path Parameters
workspaceIdWorkspace UUID
taskIdTask UUID
Save the verification summary › Request Body
summaryVerification summary written as a session log entry. Should describe what was verified and any uploaded screenshots.
attachmentIdsIDs of attachments you uploaded with request-attachment-upload. Images uploaded to this session (entity session) show with the summary in the session's conversation and in its snippets strip; images uploaded to a task are only listed by id in the task logs.
taskIdsTask IDs in the session. When provided, the verification summary is also written as a task log on each task in the set, in addition to the session log.
Save the verification summary › Responses
Verification recorded
Mark task work complete (PR opened)
Sets pullRequestUrl on the session, sets each task to status=reviewing, and adds session + task log entries about the PR. By default operates on every task in the session containing :taskId; pass an explicit taskIds list to scope to a subset.
path Parameters
workspaceIdWorkspace UUID
taskIdTask UUID
Mark task work complete (PR opened) › Request Body
pullRequestUrlURL of the pull request that contains the implementation.
taskIdsOptional list of task IDs to mark complete. If omitted, all tasks linked to the same session as the path :taskId are used.
Mark task work complete (PR opened) › Responses
Updated session and tasks
List development tasks in a workspace
Returns tasks that track implementation work. A task's structural parent is a feature, an application or a session (parentEntityType/parentEntityId; featureId remains a deprecated feature-only alias). Tasks have a status flow (todo, in_planning, in_progress, in_testing, in_review, done) and can be assigned to users. By default returns flat tasks with NO parent object — pass ?includeFeature=true to resolve each row's parentEntity (lean: entityType, id, title, displayId) plus the deprecated feature alias when the parent is a feature. Returns: id, title, description, status, priority, assigneeId, creatorId, childCount, startAt, dueAt, sortOrder.
path Parameters
workspaceIdWorkspace UUID
query Parameters
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
statusFilter by task status (single value or array)
priorityFilter by priority (single value or array)
assigneeIdFilter by assignee: a user or team UUID, or a comma-separated list of them (tasks assigned to ANY listed user/team match). my-teams stands for every team the caller belongs to, and for-me for the tasks FOR the caller: assigned to them, or in the view of a team they are on (assigned to the team, under a feature in its area, or a sub-task of such a task). for-me is the sidebar's Tasks count.
teamIdFilter to a TEAM's area: a team UUID, or a comma-separated list of them (items in the area of ANY listed team match). my-teams stands for every team the caller belongs to. An item is in a team's area when it is assigned to the team, or sits under a feature assigned to it, at any depth: a feature's sub-features, their tasks and sub-tasks, the bug reports linked to those features and tasks, and the coding sessions working on them. Unlike assigneeId, which matches only items assigned directly. A user id matches nothing, and so does my-teams for a caller on no team.
featureIdFilter by parent feature UUID (tasks whose structural parent is that feature)
parentEntityTypeComma-separated structural-parent types to filter by: feature, application, session, or none ('none' matches tasks with no parent). Unknown values are rejected.
parentEntityIdFilter by structural parent UUID (any parent type).
includeSubfeaturesWhen combined with featureId, also return tasks of every descendant subfeature (full subtree). Defaults to false — only tasks directly linked to the given feature are returned.
sessionIdFilter by session UUID. Returns tasks linked to that session via SessionItem
parentTaskIdFilter by parent task UUID. Omit to get only root tasks (no parent). Use 'all' for all tasks
includeFeatureOpt in to resolve each task's structural parent: the parentEntity object (feature, application or session, lean projection) plus the deprecated feature alias when the parent is a feature. Defaults to false — the list returns flat tasks with no parent object.
tagsComma-separated tag names to filter by
includeSessionsOpt in to each task's sessions: the coding sessions it is in (id, displayId, name, category, status), scans and code chats left out. Returned only to a caller who may read coding sessions. Defaults to false. sortBy=codingSession orders the tasks by their current session: the newest one working on the task, else the newest still in planning, else the newest finished one; tasks in no session come last.
activityAfter^(?:(?:\d\d[2468][04…Only the items with activity after this ISO 8601 instant (for example 2026-10-26T09:00:00Z): for a session its last activity, or its last update when it has none; for every other list its last update (updatedAt). Send it with limit=1 and read pagination.total to count what changed since then. The response names the instant it applied in filters.activityAfter. A value that is not an ISO 8601 instant is refused with 400.
List development tasks in a workspace › Responses
List of tasks
Create a development task
Create a task to track implementation work. Tasks can be linked to a structural parent (a feature, an application or a session — parentEntityType/parentEntityId) and organized in a parent/child hierarchy. Status: todo, in_planning, in_progress, in_testing, in_review, done. When you are creating this from a conversation, pass that conversation's id as originChatId — the newest images the user attached there are copied onto the task.
path Parameters
workspaceIdWorkspace UUID
Create a development task › Request Body
titledescriptionMarkdown, at most 200,000 characters.
statustypepriorityassigneeIdAssign ONE user by UUID (the legacy single-assignee field). Use assignees to assign several people or a team.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
creatorIdCreator user UUID (required for service/agent callers)
featureIdDeprecated alias for parentEntityType:'feature' + parentEntityId — kept for existing agents. Supplying it alongside the parentEntityType/parentEntityId pair is a 400.
parentEntityTypeThe structural parent's entity type (feature | application | session). Pair with parentEntityId — both or neither. NOTE: parentId is the parent TASK (subtask nesting), an unrelated axis.
parentEntityIdThe structural parent's UUID. Pair with parentEntityType — both or neither.
parentIdParent TASK UUID (subtask nesting) — NOT the structural parent; see parentEntityType.
startAtdueAtsortOrderpositionWhere to place the task among its siblings (same structural parent and same parent task) when sortOrder is not supplied. end appends it below the last sibling, start puts it above the first. Ignored when an explicit sortOrder is given.
externalSourceexternalIdexternalSourceUrltagsLayer tags for the task (e.g. backend, frontend, agent, test, docs, infra).
originChatId^([0-9a-fA-F]{8}-[0-…The Conversation id from your context. Pass it when you are creating this from a conversation so the images the user attached travel onto the item.
Create a development task › Responses
Created task
List log entries on a task
Returns all log entries recorded against a task. Logs track implementation progress and notes. Returns: id, content, createdById, createdByName, createdAt.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
query Parameters
taskIdTask UUID
pagePage number (1-indexed, default 1)
limitItems per page (default 50)
sortByField to sort by
sortOrderSort direction (default desc)
searchFull-text search across searchable fields
List log entries on a task › Responses
List of log entries
Add a log entry to a task
Record a log entry to track implementation progress, decisions, and notes.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
Add a log entry to a task › Responses
Log entry added
Update a task log entry
Update the content of a specific log entry on a task. Only the log author can edit it.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
logIdLog UUID
Update a task log entry › Responses
Updated log entry
Get a task by ID
Retrieve a single task with full details including linked feature, assignee, comments, sessions, and attachments.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
Get a task by ID › Responses
Task details
Update a development task
Modify task title, description, status, priority, or other fields.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
Update a development task › Request Body
titleMarkdown, at most 200,000 characters. Replaces the whole description: send it only with the complete new text. To change part of the description, send descriptionEdits instead.
Change PART of the description without resending it: a list of exact find-and-replace edits the server applies to the stored description, in order, all or none. Each find must be copied exactly (same characters, spacing and line breaks) from the description as it stands, and must occur exactly once there at that point: include enough surrounding text to make it unique. replace is the new text (an empty string deletes the passage). Everything outside the passages is kept as it is. Prefer this over description for any change to a long description, and always when your read of the description was cut. Cannot be sent together with description.
statustypeprioritySet the single USER assignee (legacy field): replaces the task's user assignees with this one, null unassigns every user. Team assignees are left untouched — use assignees to change them.
REPLACES the item's whole assignee set: every user and team listed becomes an assignee, everything not listed is unassigned. Pass [] to unassign everyone. When both this and the legacy single-user field (assigneeId / ownerId) are supplied, this wins. Find a team's id with list-teams and a person's with list-assignable-users.
Deprecated alias for parentEntityType:'feature' + parentEntityId (null clears the parent). Supplying it alongside the pair is a 400.
The structural parent's entity type. Pair with parentEntityId — both set, or both null to detach.
The structural parent's UUID. Pair with parentEntityType — both set, or both null to detach.
Parent TASK UUID (subtask nesting) — NOT the structural parent.
sortOrderUpdate a development task › Responses
Updated task
Describe a task from its screenshots
Trigger the vision agent to read the task's attached screenshots and draft an updated description, incorporating the title, the existing description, the parent feature and the workspace's task description template. Idempotent while a run is in flight. On a blank description the draft is applied automatically; otherwise it is held for review.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
Describe a task from its screenshots › Request Body
sourceHow the run was triggered (auto on image upload / manual button)
Describe a task from its screenshots › Responses
The queued (or in-flight) description proposal
List a task's description proposals
Returns AI-drafted description proposals for a task. Pass activeOnly=true for the single in-flight / awaiting-review proposal.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
query Parameters
activeOnlyList a task's description proposals › Responses
Description proposals
Apply a task description proposal
Write the reviewer-composed markdown (accepted diff blocks) to the task's description and settle the proposal.
path Parameters
workspaceIdWorkspace UUID
idTask UUID
proposalIdProposal UUID
Apply a task description proposal › Request Body
descriptionApply a task description proposal › Responses
The applied proposal