tasks
tasks.comment
tasks.comment
Effects: write
Post a comment on a task. Attach files (screenshots, documents) by uploading them with files.upload first and passing the file IDs.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Comment as this agent instead of as yourself. Optional. |
attachment_file_ids | array | no | File IDs to attach (from files.upload) |
body | string | yes | Comment text |
task_id | integer | yes | Task to comment on |
tasks.create
tasks.create
Effects: write
Create a task in this workspace. Leave the assignee empty to put it in the backlog, or name someone to hand it over.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Act as this agent instead of as yourself — the task is recorded as authored by it. Optional. |
assigned_to_contact_id | integer | no | Exact contact to assign to |
assignee | string | no | Who should do this: a workspace member (email or username), an AI agent (its name), or a contact (display name). Use 'me' for yourself. Call workspace.members to see who can be assigned. For an exact target, pass assignee_user_id / assignee_agent_id / assigned_to_contact_id instead. |
assignee_agent_id | integer | no | Exact AI agent to assign to |
assignee_user_id | integer | no | Exact workspace member to assign to |
attachment_file_ids | array | no | File IDs to attach (from files.upload) |
description | string | no | Detailed description |
due_at | string | no | ISO datetime when the task is due, e.g. '2026-03-31T15:00:00Z'. A time without a zone is read as UTC. |
due_date | string | no | Date when task is due (e.g. '2026-03-31'). Use with due_time or alone. |
due_time | string | no | Time when task is due (e.g. '15:00'). Used with due_date. |
priority | string | no | Task priority (default: medium) (one of low, medium, high, urgent) |
target_session | string | no | Which desktop Claude session should run this, by the name shown in workspace.desktops. Only needed when the assignee is an AI agent that runs on a machine and more than one session is connected — otherwise the task is not dispatched at all, rather than sent to a machine you did not mean. |
thread_id | integer | no | Related thread ID |
title | string | yes | Task title |
tasks.delete
tasks.delete
Effects: write
Delete a task. Only its creator or a workspace owner/admin may do this; to close a task instead, set status='cancelled'.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Act as this agent instead of as yourself. Optional. |
task_id | integer | yes | ID of the task to delete |
tasks.get
tasks.get
Effects: read
Read one task in full: its fields, attachments, and the whole comment thread including recorded status and assignee changes. Pass agent_id when you are acting as an agent, and the reply says assigned_to_me so you need not infer it from matching ids.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Read as this agent. Set it to your own agent_id to be told whether the task is assigned to you. |
task_id | integer | yes | ID of the task to read |
tasks.list
tasks.list
Effects: read
List tasks in this workspace. Defaults to everything a person can see; an agent calling this sees its own tasks. Filter by assignee, status, or overdue to narrow it down.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Show one agent's own tasks instead of the whole workspace. Optional. |
assigned_to_contact_id | integer | no | |
assignee | string | no | Only tasks assigned to this member / agent / contact. Use 'me' for your own. |
assignee_agent_id | integer | no | |
assignee_user_id | integer | no | |
created_by_me | boolean | no | Only tasks you created |
limit | integer | no | Max results per page (default 20, max 100) |
offset | integer | no | Skip this many results — use with limit to page through |
overdue | boolean | no | Only tasks past their due date that are not finished |
status | string | no | one of pending, in_progress, done, cancelled |
thread_id | integer | no | Filter by related thread |
unassigned | boolean | no | Only tasks with nobody assigned (the backlog) |
tasks.update
tasks.update
Effects: write
Update a task. Set status='done' to complete it, 'cancelled' to cancel. Reassign with assignee. Status and assignee changes are recorded in the task's comment thread.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
agent_id | integer | no | Act as this agent instead of as yourself. Optional. |
assigned_to_contact_id | integer | no | |
assignee | string | no | Who should do this: a workspace member (email or username), an AI agent (its name), or a contact (display name). Use 'me' for yourself. Call workspace.members to see who can be assigned. For an exact target, pass assignee_user_id / assignee_agent_id / assigned_to_contact_id instead. |
assignee_agent_id | integer | no | |
assignee_user_id | integer | no | |
attachment_file_ids | array | no | Replace the task's attachments with these file IDs |
clear_assignee | boolean | no | Unassign the task, returning it to the backlog |
description | string | no | |
due_at | string | no | ISO datetime |
priority | string | no | one of low, medium, high, urgent |
status | string | no | one of pending, in_progress, done, cancelled |
summary | string | no | Completion note (stored when marking done) |
target_session | string | no | Which desktop Claude session should run this, by the name shown in workspace.desktops. Only needed when the assignee is an AI agent that runs on a machine and more than one session is connected — otherwise the task is not dispatched at all, rather than sent to a machine you did not mean. |
task_id | integer | yes | ID of the task to update |
title | string | no |