Tasks - Doers

19 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.

Tool	What it does	Kind
`get_task`	Get a task	Read · idempotent · no outside service
`get_tasks`	Get several tasks by id	Read · idempotent · no outside service
`list_inbox_history`	Tasks you have already triaged	Read · idempotent · no outside service
`list_task_members`	List the people with access to a task	Read · idempotent · no outside service
`list_tasks`	List the tasks	Read · idempotent · no outside service
`add_checklist_items`	Add checklist items	Write · no outside service
`archive_tasks`	Archive or restore tasks	Write · destructive · no outside service
`assign_task`	Assign a task to someone, or to nobody	Write · idempotent · no outside service
`check_checklist_items`	Tick checklist items	Write · idempotent · no outside service
`complete_tasks`	Tick or untick tasks	Write · no outside service
`create_task`	Create a task	Write · no outside service
`create_tasks`	Create several tasks atomically	Write · no outside service
`delete_task`	Delete an archived task for good	Write · destructive · idempotent · no outside service
`quick_add_task`	Create a task from natural language	Write · no outside service
`reorder_hierarchy`	Move tasks and projects atomically	Write · idempotent · no outside service
`schedule_tasks`	Schedule tasks atomically	Write · idempotent · no outside service
`set_checklist`	Replace a task’s checklist	Write · idempotent · no outside service
`update_task`	Update a task	Write · idempotent · no outside service
`update_tasks`	Update several tasks at once	Write · idempotent · no outside service

get_task

Get a task. Returns a full task (notes, checklist, attachment) and your access role. Returns 404 if the task does not exist or is not accessible to you: the API never reveals the existence of another account’s task.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/tasks/{taskId}`
CLI	`doers tasks get`
Touches	`taskMembers`, `tasks`, `user`
Operation	`getTask`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`task`	object
`task.id`	string
`task.title`	string
`task.notes`	string
`task.status`	string	`open`, `done`, `archived`
`task.priority`	integer	-9007199254740991 to 9007199254740991
`task.when`	object		How the task is scheduled (distinct from its `deadline`).
`task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`task.when.date`	string (optional)
`task.when.hasTime`	boolean (optional)
`task.when.time`	string \| null (optional)
`task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`task.projectId`	string \| null
`task.areaId`	string \| null
`task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`task.tags`	string[]
`task.checklist`	object[]
`task.checklist[].id`	string
`task.checklist[].label`	string
`task.checklist[].done`	boolean
`task.completedAt`	number \| null
`task.durationMin`	number \| null
`task.kind`	string	`task`, `event`
`task.repeat`	object \| null
`task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`task.repeat.unit`	string	`day`, `week`, `month`, `year`
`task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`task.notePath`	string \| null	0 to 1024 characters
`task.conversationPath`	string \| null	0 to 1024 characters
`task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`task.assignee`	object \| null		The same person, as the row draws them.
`task.assignee.id`	string
`task.assignee.username`	string \| null
`task.assignee.name`	string \| null
`task.assignee.email`	string \| null
`task.assignee.image`	string \| null
`task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_task",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[0ebb429f-a86d-481c-8630-fac53db1c91c] Prepare the Acme quarterly review"
      }
    ],
    "structuredContent": {
      "task": {
        "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
        "title": "Prepare the Acme quarterly review",
        "notes": "Notes for the Acme launch.",
        "status": "open",
        "priority": 2,
        "when": {
          "kind": "today"
        },
        "deadline": "2026-09-22",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "tags": ["acme"],
        "checklist": [
          {
            "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
            "label": "Acme",
            "done": true
          }
        ],
        "completedAt": 1790069400000,
        "durationMin": 30,
        "kind": "task",
        "repeat": {
          "every": 3,
          "unit": "day",
          "mode": "calendar"
        },
        "visibility": "public",
        "order": 0,
        "notePath": "Acme/Weekly review",
        "conversationPath": "Acme/Weekly review",
        "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
        "assignee": {
          "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "username": "ada",
          "name": "Acme",
          "email": "ada@acme.example",
          "image": "https://acme.example/ada.png"
        },
        "accessRole": "owner"
      }
    }
  }
}

doers tasks get 0ebb429f-a86d-481c-8630-fac53db1c91c

get_tasks

Get several tasks by id. Resolves several task identifiers in one request, including shared tasks. Identifiers that are missing or inaccessible are returned together as unavailable, without revealing which case applies.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/tasks/by-id`
CLI	`doers tasks get-many`
Touches	`taskMembers`, `tasks`, `user`
Operation	`getTasks`

Input

Field	Type	Required	Default	Allowed values	Description
`taskIds` (query)	string[]	yes		at most 50 items, each: UUID	Ids of the tasks concerned (50 maximum).

Output

Output fields

Field	Type	Allowed values	Description
`tasks`	object[]
`tasks[].id`	string
`tasks[].title`	string
`tasks[].notes`	string
`tasks[].status`	string	`open`, `done`, `archived`
`tasks[].priority`	integer	-9007199254740991 to 9007199254740991
`tasks[].when`	object		How the task is scheduled (distinct from its `deadline`).
`tasks[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`tasks[].when.date`	string (optional)
`tasks[].when.hasTime`	boolean (optional)
`tasks[].when.time`	string \| null (optional)
`tasks[].deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`tasks[].projectId`	string \| null
`tasks[].areaId`	string \| null
`tasks[].headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`tasks[].tags`	string[]
`tasks[].checklist`	object[]
`tasks[].checklist[].id`	string
`tasks[].checklist[].label`	string
`tasks[].checklist[].done`	boolean
`tasks[].completedAt`	number \| null
`tasks[].durationMin`	number \| null
`tasks[].kind`	string	`task`, `event`
`tasks[].repeat`	object \| null
`tasks[].repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	`day`, `week`, `month`, `year`
`tasks[].repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`tasks[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`tasks[].notePath`	string \| null	0 to 1024 characters
`tasks[].conversationPath`	string \| null	0 to 1024 characters
`tasks[].assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`tasks[].assignee`	object \| null		The same person, as the row draws them.
`tasks[].assignee.id`	string
`tasks[].assignee.username`	string \| null
`tasks[].assignee.name`	string \| null
`tasks[].assignee.email`	string \| null
`tasks[].assignee.image`	string \| null
`tasks[].accessRole`	string	`owner`, `editor`, `commenter`, `reader`
`unavailableTaskIds`	string[]	each: UUID

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_tasks",
    "arguments": {
      "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1 task(s) resolved; 1 unavailable."
      }
    ],
    "structuredContent": {
      "tasks": [
        {
          "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "notes": "Notes for the Acme launch.",
          "status": "open",
          "priority": 2,
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "tags": ["acme"],
          "checklist": [
            {
              "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
              "label": "Acme",
              "done": true
            }
          ],
          "completedAt": 1790069400000,
          "durationMin": 30,
          "kind": "task",
          "repeat": {
            "every": 3,
            "unit": "day",
            "mode": "calendar"
          },
          "visibility": "public",
          "order": 0,
          "notePath": "Acme/Weekly review",
          "conversationPath": "Acme/Weekly review",
          "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "assignee": {
            "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "username": "ada",
            "name": "Acme",
            "email": "ada@acme.example",
            "image": "https://acme.example/ada.png"
          },
          "accessRole": "owner"
        }
      ],
      "unavailableTaskIds": ["c1e55d01-0182-4166-8745-042bed102ad5"]
    }
  }
}

doers tasks get-many --task-ids 0ebb429f-a86d-481c-8630-fac53db1c91c

list_inbox_history

Tasks you have already triaged. Returns the tasks that arrived in the Inbox and have since been placed, scheduled, completed or archived, most recently triaged first, with the instant each one left. Use it to look back at what an Inbox held, or to find something filed by mistake. A task created straight into a project or an area never appears here: it was never in the Inbox. A task that returned to the Inbox and was triaged again keeps the instant it first left, and appears once. Unlike listTasks, this does not exclude calendar blocks: a task turned into one left the Inbox like any other, and hiding it would make an item disappear without trace. This is the task half of the Inbox history. Agent handbacks live in the local vault and messages come from listInboxComments; the Desktop client merges the three into one chronological list.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/inbox/history`
CLI	`doers tasks list-inbox-history`
Touches	`taskMembers`, `tasks`, `user`
Operation	`listInboxHistory`

Input

Field	Type	Required	Default	Allowed values	Description
`limit` (query)	integer	no	`100`	1 to 200	How many triaged tasks to return.
`cursor` (query)	string	no		0 to 512 characters	Opaque cursor from a previous page.

Output

Output fields

Field	Type	Allowed values	Description
`items`	object[]
`items[].task`	object
`items[].task.id`	string
`items[].task.title`	string
`items[].task.notes`	string
`items[].task.status`	string	`open`, `done`, `archived`
`items[].task.priority`	integer	-9007199254740991 to 9007199254740991
`items[].task.when`	object		How the task is scheduled (distinct from its `deadline`).
`items[].task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`items[].task.when.date`	string (optional)
`items[].task.when.hasTime`	boolean (optional)
`items[].task.when.time`	string \| null (optional)
`items[].task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`items[].task.projectId`	string \| null
`items[].task.areaId`	string \| null
`items[].task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`items[].task.tags`	string[]
`items[].task.checklist`	object[]
`items[].task.checklist[].id`	string
`items[].task.checklist[].label`	string
`items[].task.checklist[].done`	boolean
`items[].task.completedAt`	number \| null
`items[].task.durationMin`	number \| null
`items[].task.kind`	string	`task`, `event`
`items[].task.repeat`	object \| null
`items[].task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`items[].task.repeat.unit`	string	`day`, `week`, `month`, `year`
`items[].task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`items[].task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`items[].task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`items[].task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`items[].task.notePath`	string \| null	0 to 1024 characters
`items[].task.conversationPath`	string \| null	0 to 1024 characters
`items[].task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`items[].task.assignee`	object \| null		The same person, as the row draws them.
`items[].task.assignee.id`	string
`items[].task.assignee.username`	string \| null
`items[].task.assignee.name`	string \| null
`items[].task.assignee.email`	string \| null
`items[].task.assignee.image`	string \| null
`items[].task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.
`items[].processedAt`	number		Epoch milliseconds at which the task first left the Inbox.
`nextCursor`	string \| null		Opaque cursor for the next page, or null.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_inbox_history",
    "arguments": {
      "limit": 100,
      "cursor": "Notes for the Acme launch."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [0ebb429f-a86d-481c-8630-fac53db1c91c] Prepare the Acme quarterly review\nMore results are available. Continue with cursor: Notes for the Acme launch."
      }
    ],
    "structuredContent": {
      "items": [
        {
          "task": {
            "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
            "title": "Prepare the Acme quarterly review",
            "notes": "Notes for the Acme launch.",
            "status": "open",
            "priority": 2,
            "when": {
              "kind": "today"
            },
            "deadline": "2026-09-22",
            "projectId": "244210e4-8437-4655-8980-a70249a99369",
            "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
            "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
            "tags": ["acme"],
            "checklist": [
              {
                "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
                "label": "Acme",
                "done": true
              }
            ],
            "completedAt": 1790069400000,
            "durationMin": 30,
            "kind": "task",
            "repeat": {
              "every": 3,
              "unit": "day",
              "mode": "calendar"
            },
            "visibility": "public",
            "order": 0,
            "notePath": "Acme/Weekly review",
            "conversationPath": "Acme/Weekly review",
            "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "assignee": {
              "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
              "username": "ada",
              "name": "Acme",
              "email": "ada@acme.example",
              "image": "https://acme.example/ada.png"
            },
            "accessRole": "owner"
          },
          "processedAt": 1790069400000
        }
      ],
      "nextCursor": "Notes for the Acme launch."
    }
  }
}

doers tasks list-inbox-history --limit 100 --cursor "Notes for the Acme launch."

list_task_members

List the people with access to a task. Returns the owner and the invited members of a task, with their role (reader, commenter, editor). A task with no invited members returns just the owner: the common case.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/tasks/{taskId}/members`
CLI	`doers tasks members`
Touches	`taskMembers`, `tasks`, `user`
Operation	`listTaskMembers`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`members`	object[]
`members[].userId`	string
`members[].label`	string		`@username`, else the name, else the email.
`members[].role`	string	`owner`, `editor`, `commenter`, `reader`

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_task_members",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- Acme (owner)"
      }
    ],
    "structuredContent": {
      "members": [
        {
          "userId": "04f8996d-a763-47a9-89b1-028ee3007569",
          "label": "Acme",
          "role": "owner"
        }
      ]
    }
  }
}

doers tasks members 0ebb429f-a86d-481c-8630-fac53db1c91c

list_tasks

List the tasks. Returns open tasks by default, in manual order. status=done returns the most recently completed first. Calendar blocks (kind: "event") are always excluded. Filterable by project, by area and by title text.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/tasks`
CLI	`doers tasks list`
Touches	`taskMembers`, `tasks`, `user`
Operation	`listTasks`

Input

Field	Type	Required	Default	Allowed values	Description
`status` (query)	string	no	`"open"`	`open`, `done`, `archived`	No description in the registry.
`projectId` (query)	string	no		UUID	Identifier of a row.
`areaId` (query)	string	no		UUID	Identifier of a row.
`query` (query)	string	no		1 to 200 characters	Search within the title.
`limit` (query)	integer	no	`100`	1 to 200	No description in the registry.
`assignedToMe` (query)	boolean	no	`false`		Only what is assigned to you, whoever owns it (`Teams 02`).
`sharedWithMe` (query)	boolean	no	`false`		Only the tasks of the projects and areas shared with you, none of your own.
`completedSince` (query)	integer	no		0 to 9007199254740991	For `status=done`, only completions at or after this epoch millisecond.
`cursor` (query)	string	no		0 to 512 characters	No description in the registry.
`workspaceId` (query)	string	no		UUID	The workspace to read within; the personal one by default (T-D11).

Output

Output fields

Field	Type	Allowed values	Description
`tasks`	object[]
`tasks[].id`	string
`tasks[].title`	string
`tasks[].notes`	string
`tasks[].status`	string	`open`, `done`, `archived`
`tasks[].priority`	integer	-9007199254740991 to 9007199254740991
`tasks[].when`	object		How the task is scheduled (distinct from its `deadline`).
`tasks[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`tasks[].when.date`	string (optional)
`tasks[].when.hasTime`	boolean (optional)
`tasks[].when.time`	string \| null (optional)
`tasks[].deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`tasks[].projectId`	string \| null
`tasks[].areaId`	string \| null
`tasks[].headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`tasks[].tags`	string[]
`tasks[].checklist`	object[]
`tasks[].checklist[].id`	string
`tasks[].checklist[].label`	string
`tasks[].checklist[].done`	boolean
`tasks[].completedAt`	number \| null
`tasks[].durationMin`	number \| null
`tasks[].kind`	string	`task`, `event`
`tasks[].repeat`	object \| null
`tasks[].repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	`day`, `week`, `month`, `year`
`tasks[].repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`tasks[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`tasks[].notePath`	string \| null	0 to 1024 characters
`tasks[].conversationPath`	string \| null	0 to 1024 characters
`tasks[].assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`tasks[].assignee`	object \| null		The same person, as the row draws them.
`tasks[].assignee.id`	string
`tasks[].assignee.username`	string \| null
`tasks[].assignee.name`	string \| null
`tasks[].assignee.email`	string \| null
`tasks[].assignee.image`	string \| null
`tasks[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.
`total`	integer	-9007199254740991 to 9007199254740991	Number of results before `limit` is applied.
`nextCursor`	string \| null		Opaque cursor for the next page, or null.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tasks",
    "arguments": {
      "status": "open",
      "projectId": "244210e4-8437-4655-8980-a70249a99369"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [0ebb429f-a86d-481c-8630-fac53db1c91c] Prepare the Acme quarterly review\nMore results are available. Continue with cursor: Notes for the Acme launch."
      }
    ],
    "structuredContent": {
      "tasks": [
        {
          "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "notes": "Notes for the Acme launch.",
          "status": "open",
          "priority": 2,
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "tags": ["acme"],
          "checklist": [
            {
              "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
              "label": "Acme",
              "done": true
            }
          ],
          "completedAt": 1790069400000,
          "durationMin": 30,
          "kind": "task",
          "repeat": {
            "every": 3,
            "unit": "day",
            "mode": "calendar"
          },
          "visibility": "public",
          "order": 0,
          "notePath": "Acme/Weekly review",
          "conversationPath": "Acme/Weekly review",
          "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "assignee": {
            "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "username": "ada",
            "name": "Acme",
            "email": "ada@acme.example",
            "image": "https://acme.example/ada.png"
          },
          "accessRole": "owner"
        }
      ],
      "total": 3,
      "nextCursor": "Notes for the Acme launch."
    }
  }
}

doers tasks list --status open --project-id 244210e4-8437-4655-8980-a70249a99369

add_checklist_items

Add checklist items. Adds items without overwriting the existing ones. Labels already present (case-insensitive comparison) are silently skipped.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks/{taskId}/checklist`
CLI	`doers tasks checklist-add`
Touches	`checklistItems`
Operation	`addChecklistItems`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.
`items`	string[]	yes		at most 30 items, each: 1 to 300 characters	No description in the registry.

Output

Output fields

Field	Type	Allowed values
`checklist`	object[]
`checklist[].id`	string
`checklist[].label`	string
`checklist[].done`	boolean
`added`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_checklist_items",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "items": ["Notes for the Acme launch."]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 3 checklist item(s) added."
      }
    ],
    "structuredContent": {
      "checklist": [
        {
          "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
          "label": "Acme",
          "done": true
        }
      ],
      "added": 3
    }
  }
}

doers tasks checklist-add 0ebb429f-a86d-481c-8630-fac53db1c91c --items "Notes for the Acme launch."

archive_tasks

Archive or restore tasks. Archiving is reversible: it replaces deletion and is undone with restore: true. There is deliberately no permanent delete in this API. Owner only.


Kind	Write · destructive · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks/archive`
CLI	`doers tasks archive`
Touches	`areas`, `projects`, `tasks`
Operation	`archiveTasks`

Input

Field	Type	Required	Default	Allowed values	Description
`taskIds`	string[]	yes		at most 50 items, each: UUID	Ids of the tasks concerned (50 maximum).
`restore`	boolean	no	`false`		`true` to unarchive and put the task back in progress.

Output

Output fields

Field	Type	Allowed values	Description
`count`	integer	-9007199254740991 to 9007199254740991
`restored`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "archive_tasks",
    "arguments": {
      "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
      "restore": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 3 task(s) restored."
      }
    ],
    "structuredContent": {
      "count": 3,
      "restored": true
    }
  }
}

doers tasks archive --task-ids 0ebb429f-a86d-481c-8630-fac53db1c91c --restore false

assign_task

Assign a task to someone, or to nobody. username names someone who already reaches the task; anyone else is not found. null clears the assignment. Takes Can edit. An optional grant accepts only an exact existing handle and atomically grants direct task-only access before assigning; only the task owner may use it and existing guest role ceilings still apply.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/tasks/{taskId}/assignee`
CLI	`doers tasks assign`
Touches	`taskMembers`, `tasks`
Operation	`assignTask`

Input

Field	Type	Required	Allowed values	Description
`taskId` (path)	string	yes	UUID	Identifier of a row.
`username`	string \| null	yes	1 to 200 characters	No description in the registry.
`grant`	object	no		An explicit direct-task grant to create atomically before assignment.
`grant.role`	string	yes	`reader`, `commenter`, `editor`	No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`task`	object
`task.id`	string
`task.title`	string
`task.notes`	string
`task.status`	string	`open`, `done`, `archived`
`task.priority`	integer	-9007199254740991 to 9007199254740991
`task.when`	object		How the task is scheduled (distinct from its `deadline`).
`task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`task.when.date`	string (optional)
`task.when.hasTime`	boolean (optional)
`task.when.time`	string \| null (optional)
`task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`task.projectId`	string \| null
`task.areaId`	string \| null
`task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`task.tags`	string[]
`task.checklist`	object[]
`task.checklist[].id`	string
`task.checklist[].label`	string
`task.checklist[].done`	boolean
`task.completedAt`	number \| null
`task.durationMin`	number \| null
`task.kind`	string	`task`, `event`
`task.repeat`	object \| null
`task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`task.repeat.unit`	string	`day`, `week`, `month`, `year`
`task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`task.notePath`	string \| null	0 to 1024 characters
`task.conversationPath`	string \| null	0 to 1024 characters
`task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`task.assignee`	object \| null		The same person, as the row draws them.
`task.assignee.id`	string
`task.assignee.username`	string \| null
`task.assignee.name`	string \| null
`task.assignee.email`	string \| null
`task.assignee.image`	string \| null
`task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "assign_task",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "username": "ada"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: assigned to 53a9d65d-3627-4bc7-8170-af8d57e84d02."
      }
    ],
    "structuredContent": {
      "task": {
        "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
        "title": "Prepare the Acme quarterly review",
        "notes": "Notes for the Acme launch.",
        "status": "open",
        "priority": 2,
        "when": {
          "kind": "today"
        },
        "deadline": "2026-09-22",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "tags": ["acme"],
        "checklist": [
          {
            "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
            "label": "Acme",
            "done": true
          }
        ],
        "completedAt": 1790069400000,
        "durationMin": 30,
        "kind": "task",
        "repeat": {
          "every": 3,
          "unit": "day",
          "mode": "calendar"
        },
        "visibility": "public",
        "order": 0,
        "notePath": "Acme/Weekly review",
        "conversationPath": "Acme/Weekly review",
        "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
        "assignee": {
          "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "username": "ada",
          "name": "Acme",
          "email": "ada@acme.example",
          "image": "https://acme.example/ada.png"
        },
        "accessRole": "owner"
      }
    }
  }
}

doers tasks assign --task-id 0ebb429f-a86d-481c-8630-fac53db1c91c --username ada

check_checklist_items

Tick checklist items. Ticks (or unticks with done: false) items named by their id or by their exact label, case-insensitively.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/tasks/{taskId}/checklist`
CLI	`doers tasks checklist-check`
Touches	`checklistItems`
Operation	`checkChecklistItems`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.
`items`	string[]	yes		at most 30 items	No description in the registry.
`done`	boolean	no	`true`		No description in the registry.

Output

Output fields

Field	Type	Allowed values
`checklist`	object[]
`checklist[].id`	string
`checklist[].label`	string
`checklist[].done`	boolean
`changed`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_checklist_items",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "items": ["Notes for the Acme launch."],
      "done": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 3 checklist item(s) changed."
      }
    ],
    "structuredContent": {
      "checklist": [
        {
          "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
          "label": "Acme",
          "done": true
        }
      ],
      "changed": 3
    }
  }
}

doers tasks checklist-check 0ebb429f-a86d-481c-8630-fac53db1c91c --items "Notes for the Acme launch." --done true

complete_tasks

Tick or untick tasks. Marks tasks as done, or reopens them with done: false.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks/complete`
CLI	`doers tasks complete`
Touches	`areas`, `projects`, `tasks`
Operation	`completeTasks`

Input

Field	Type	Required	Default	Allowed values	Description
`taskIds`	string[]	yes		at most 50 items, each: UUID	Ids of the tasks concerned (50 maximum).
`done`	boolean	no	`true`		No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`count`	integer	-9007199254740991 to 9007199254740991
`done`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "complete_tasks",
    "arguments": {
      "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
      "done": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 3 task(s) completed."
      }
    ],
    "structuredContent": {
      "count": 3,
      "done": true
    }
  }
}

doers tasks complete --task-ids 0ebb429f-a86d-481c-8630-fac53db1c91c --done true

create_task

Create a task. Creates a task from structured fields. To create from a sentence, use POST /v2/tasks/quick instead. A task belongs to a project or to an area, never both: if projectId is given, areaId is ignored.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks`
CLI	`doers tasks create`
Touches	`areas`, `projects`, `tasks`
Operation	`createTask`

Input

Field	Type	Required	Allowed values	Description
`title`	string	yes	1 to 500 characters	No description in the registry.
`requestId`	string	no	UUID	Stable creation request identifier. Reusing it returns the first task. If that task has been deleted, the request remains consumed and returns a conflict.
`notes`	string	no	0 to 10000 characters	Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. Do not use code blocks (```) or images: the app’s editor does not support them and truncates the display from that point on.
`when`	string	no	`today`, `anytime`, `someday`; `YYYY-MM-DD`	Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.
`time`	string	no	`HH:MM`	Time `HH:MM`: only meaningful alongside a date.
`deadline`	string \| null	no	`YYYY-MM-DD`	Due date, distinct from `when`.
`priority`	integer	no	0 to 4	0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.
`projectId`	string \| null	no	UUID	No description in the registry.
`areaId`	string \| null	no	UUID	No description in the registry.
`headingId`	string \| null	no	UUID	Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.
`tags`	string[]	no	at most 20 items	No description in the registry.
`durationMin`	integer	no	15 to 1440	No description in the registry.
`conversationPath`	string	no	0 to 1024 characters	Local Atelier conversation carrying this delegated task.
`kind`	string	no	`task`, `event`	`event` is a calendar block, excluded from task lists.
`repeat`	object \| null	no		Repeat rule. `null` stops it repeating.
`repeat.every`	integer	yes	1 to 365	The multiplier: 2 × week.
`repeat.unit`	string	yes	`day`, `week`, `month`, `year`	No description in the registry.
`repeat.mode`	string	yes	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`repeat.weekdays`	integer[]	no	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`visibility`	string	no	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces. Defaults to private on create.
`order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`task`	object
`task.id`	string
`task.title`	string
`task.notes`	string
`task.status`	string	`open`, `done`, `archived`
`task.priority`	integer	-9007199254740991 to 9007199254740991
`task.when`	object		How the task is scheduled (distinct from its `deadline`).
`task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`task.when.date`	string (optional)
`task.when.hasTime`	boolean (optional)
`task.when.time`	string \| null (optional)
`task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`task.projectId`	string \| null
`task.areaId`	string \| null
`task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`task.tags`	string[]
`task.checklist`	object[]
`task.checklist[].id`	string
`task.checklist[].label`	string
`task.checklist[].done`	boolean
`task.completedAt`	number \| null
`task.durationMin`	number \| null
`task.kind`	string	`task`, `event`
`task.repeat`	object \| null
`task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`task.repeat.unit`	string	`day`, `week`, `month`, `year`
`task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`task.notePath`	string \| null	0 to 1024 characters
`task.conversationPath`	string \| null	0 to 1024 characters
`task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`task.assignee`	object \| null		The same person, as the row draws them.
`task.assignee.id`	string
`task.assignee.username`	string \| null
`task.assignee.name`	string \| null
`task.assignee.email`	string \| null
`task.assignee.image`	string \| null
`task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "title": "Prepare the Acme quarterly review",
      "notes": "Notes for the Acme launch.",
      "when": "today"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: task “Prepare the Acme quarterly review” created [0ebb429f-a86d-481c-8630-fac53db1c91c]."
      }
    ],
    "structuredContent": {
      "task": {
        "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
        "title": "Prepare the Acme quarterly review",
        "notes": "Notes for the Acme launch.",
        "status": "open",
        "priority": 2,
        "when": {
          "kind": "today"
        },
        "deadline": "2026-09-22",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "tags": ["acme"],
        "checklist": [
          {
            "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
            "label": "Acme",
            "done": true
          }
        ],
        "completedAt": 1790069400000,
        "durationMin": 30,
        "kind": "task",
        "repeat": {
          "every": 3,
          "unit": "day",
          "mode": "calendar"
        },
        "visibility": "public",
        "order": 0,
        "notePath": "Acme/Weekly review",
        "conversationPath": "Acme/Weekly review",
        "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
        "assignee": {
          "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "username": "ada",
          "name": "Acme",
          "email": "ada@acme.example",
          "image": "https://acme.example/ada.png"
        },
        "accessRole": "owner"
      }
    }
  }
}

doers tasks create "Prepare the Acme quarterly review" --notes "Notes for the Acme launch." --when today

create_tasks

Create several tasks atomically. Creates an ordered task list in one atomic operation. If any parent or heading is invalid, no task is created. Use this for multi-line paste instead of firing several create_task calls.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks/batch`
CLI	`doers tasks create-many`
Touches	`areas`, `projects`, `tasks`
Operation	`createTasks`

Input

Field	Type	Required	Allowed values	Description
`tasks`	object[]	yes	at most 50 items	No description in the registry.
`tasks[].title`	string	yes	1 to 500 characters	No description in the registry.
`tasks[].requestId`	string	no	UUID	Stable creation request identifier. Reusing it returns the first task. If that task has been deleted, the request remains consumed and returns a conflict.
`tasks[].notes`	string	no	0 to 10000 characters	Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. Do not use code blocks (```) or images: the app’s editor does not support them and truncates the display from that point on.
`tasks[].when`	string	no	`today`, `anytime`, `someday`; `YYYY-MM-DD`	Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.
`tasks[].time`	string	no	`HH:MM`	Time `HH:MM`: only meaningful alongside a date.
`tasks[].deadline`	string \| null	no	`YYYY-MM-DD`	Due date, distinct from `when`.
`tasks[].priority`	integer	no	0 to 4	0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.
`tasks[].projectId`	string \| null	no	UUID	No description in the registry.
`tasks[].areaId`	string \| null	no	UUID	No description in the registry.
`tasks[].headingId`	string \| null	no	UUID	Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.
`tasks[].tags`	string[]	no	at most 20 items	No description in the registry.
`tasks[].durationMin`	integer	no	15 to 1440	No description in the registry.
`tasks[].conversationPath`	string	no	0 to 1024 characters	Local Atelier conversation carrying this delegated task.
`tasks[].kind`	string	no	`task`, `event`	`event` is a calendar block, excluded from task lists.
`tasks[].repeat`	object \| null	no		Repeat rule. `null` stops it repeating.
`tasks[].repeat.every`	integer	yes	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	yes	`day`, `week`, `month`, `year`	No description in the registry.
`tasks[].repeat.mode`	string	yes	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[]	no	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	no	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces. Defaults to private on create.
`tasks[].order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`tasks`	object[]
`tasks[].id`	string
`tasks[].title`	string
`tasks[].notes`	string
`tasks[].status`	string	`open`, `done`, `archived`
`tasks[].priority`	integer	-9007199254740991 to 9007199254740991
`tasks[].when`	object		How the task is scheduled (distinct from its `deadline`).
`tasks[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`tasks[].when.date`	string (optional)
`tasks[].when.hasTime`	boolean (optional)
`tasks[].when.time`	string \| null (optional)
`tasks[].deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`tasks[].projectId`	string \| null
`tasks[].areaId`	string \| null
`tasks[].headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`tasks[].tags`	string[]
`tasks[].checklist`	object[]
`tasks[].checklist[].id`	string
`tasks[].checklist[].label`	string
`tasks[].checklist[].done`	boolean
`tasks[].completedAt`	number \| null
`tasks[].durationMin`	number \| null
`tasks[].kind`	string	`task`, `event`
`tasks[].repeat`	object \| null
`tasks[].repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	`day`, `week`, `month`, `year`
`tasks[].repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`tasks[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`tasks[].notePath`	string \| null	0 to 1024 characters
`tasks[].conversationPath`	string \| null	0 to 1024 characters
`tasks[].assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`tasks[].assignee`	object \| null		The same person, as the row draws them.
`tasks[].assignee.id`	string
`tasks[].assignee.username`	string \| null
`tasks[].assignee.name`	string \| null
`tasks[].assignee.email`	string \| null
`tasks[].assignee.image`	string \| null
`tasks[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_tasks",
    "arguments": {
      "tasks": [
        {
          "title": "Prepare the Acme quarterly review"
        }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 1 task(s) created."
      }
    ],
    "structuredContent": {
      "tasks": [
        {
          "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "notes": "Notes for the Acme launch.",
          "status": "open",
          "priority": 2,
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "tags": ["acme"],
          "checklist": [
            {
              "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
              "label": "Acme",
              "done": true
            }
          ],
          "completedAt": 1790069400000,
          "durationMin": 30,
          "kind": "task",
          "repeat": {
            "every": 3,
            "unit": "day",
            "mode": "calendar"
          },
          "visibility": "public",
          "order": 0,
          "notePath": "Acme/Weekly review",
          "conversationPath": "Acme/Weekly review",
          "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "assignee": {
            "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "username": "ada",
            "name": "Acme",
            "email": "ada@acme.example",
            "image": "https://acme.example/ada.png"
          },
          "accessRole": "owner"
        }
      ]
    }
  }
}

doers tasks create-many
# tasks: structured argument(s) the CLI cannot pass as flags.

delete_task

Delete an archived task for good. Removes a task permanently. The task must already be archived: POST /v2/tasks/archive first. The irreversible step is deliberately reachable only from the reversible one, which is why archive is what an agent should reach for and this is not. Owner only.


Kind	Write · destructive · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`DELETE https://api.doers.sh/v2/tasks/{taskId}`
CLI	`doers tasks delete`
Touches	`areas`, `projects`, `tasks`
Operation	`deleteTask`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`taskId`	string

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_task",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: task deleted for good."
      }
    ],
    "structuredContent": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
    }
  }
}

doers tasks delete 0ebb429f-a86d-481c-8630-fac53db1c91c

quick_add_task

Create a task from natural language. Creates a task from a sentence, using the same parser as the app’s omnibar. It reads English and French. Three families of token, combinable in any order:

! to !!! (priority 1 to 3
#name) project, else area (prefix match, accent-insensitive)
a date in English or French: “tomorrow”, “monday 3pm”, “tmr”

Anything not recognised stays in the title. Example: !!! edit the video #YouTube tomorrow 3pm.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/tasks/quick`
CLI	`doers tasks quick`
Touches	`areas`, `projects`, `tasks`
Operation	`quickAddTask`

Input

Field	Type	Required	Default	Allowed values	Description
`raw`	string	yes		1 to 500 characters	No description in the registry.
`deadline`	string \| null	no		`YYYY-MM-DD`	No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`task`	object
`task.id`	string
`task.title`	string
`task.notes`	string
`task.status`	string	`open`, `done`, `archived`
`task.priority`	integer	-9007199254740991 to 9007199254740991
`task.when`	object		How the task is scheduled (distinct from its `deadline`).
`task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`task.when.date`	string (optional)
`task.when.hasTime`	boolean (optional)
`task.when.time`	string \| null (optional)
`task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`task.projectId`	string \| null
`task.areaId`	string \| null
`task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`task.tags`	string[]
`task.checklist`	object[]
`task.checklist[].id`	string
`task.checklist[].label`	string
`task.checklist[].done`	boolean
`task.completedAt`	number \| null
`task.durationMin`	number \| null
`task.kind`	string	`task`, `event`
`task.repeat`	object \| null
`task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`task.repeat.unit`	string	`day`, `week`, `month`, `year`
`task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`task.notePath`	string \| null	0 to 1024 characters
`task.conversationPath`	string \| null	0 to 1024 characters
`task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`task.assignee`	object \| null		The same person, as the row draws them.
`task.assignee.id`	string
`task.assignee.username`	string \| null
`task.assignee.name`	string \| null
`task.assignee.email`	string \| null
`task.assignee.image`	string \| null
`task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.
`parsed`	object
`parsed.title`	string
`parsed.priority`	integer	-9007199254740991 to 9007199254740991
`parsed.projectId`	string \| null
`parsed.areaId`	string \| null

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "quick_add_task",
    "arguments": {
      "raw": "Call the Acme accountant tomorrow at 10:00",
      "deadline": "2026-09-22"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: task “Prepare the Acme quarterly review” created [0ebb429f-a86d-481c-8630-fac53db1c91c]."
      }
    ],
    "structuredContent": {
      "task": {
        "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
        "title": "Prepare the Acme quarterly review",
        "notes": "Notes for the Acme launch.",
        "status": "open",
        "priority": 2,
        "when": {
          "kind": "today"
        },
        "deadline": "2026-09-22",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "tags": ["acme"],
        "checklist": [
          {
            "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
            "label": "Acme",
            "done": true
          }
        ],
        "completedAt": 1790069400000,
        "durationMin": 30,
        "kind": "task",
        "repeat": {
          "every": 3,
          "unit": "day",
          "mode": "calendar"
        },
        "visibility": "public",
        "order": 0,
        "notePath": "Acme/Weekly review",
        "conversationPath": "Acme/Weekly review",
        "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
        "assignee": {
          "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "username": "ada",
          "name": "Acme",
          "email": "ada@acme.example",
          "image": "https://acme.example/ada.png"
        },
        "accessRole": "owner"
      },
      "parsed": {
        "title": "Prepare the Acme quarterly review",
        "priority": 2,
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
      }
    }
  }
}

doers tasks quick "Call the Acme accountant tomorrow at 10:00" --deadline 2026-09-22

reorder_hierarchy

Move tasks and projects atomically. Commits every supplied order and parent change in one database transaction. A task has exactly one explicit destination: the root, an area, or a project, optionally under a heading in that destination. A project has exactly one destination: the root or an area. If any item, destination, permission, or heading is invalid, nothing moves.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/hierarchy/reorder`
CLI	`doers tasks reorder`
Touches	`areas`, `projects`, `tasks`
Operation	`reorderHierarchy`

Input

Field	Type	Required	Allowed values	Description
`workspaceId`	string	no	UUID	Optional workspace assertion. Omit it for legacy clients; the server always derives the authoritative workspace from the moved entities.
`moves`	object[]	yes	at most 50 items	Task and project moves committed together (50 maximum).
`moves[].kind`	string	yes	`task`, `project`	No description in the registry.
`moves[].taskId`	string	no	UUID	Identifier of a row.
`moves[].order`	number	yes		Manual position. Fractional values are valid; lower sorts first.
`moves[].parent`	object	yes		No description in the registry.
`moves[].parent.kind`	string	yes	`root`, `area`, `project`	No description in the registry.
`moves[].parent.areaId`	string	no	UUID	Identifier of a row.
`moves[].parent.headingId`	string \| null	no	UUID	No description in the registry.
`moves[].parent.projectId`	string	no	UUID	Identifier of a row.
`moves[].projectId`	string	no	UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`tasks`	object[]
`tasks[].id`	string
`tasks[].title`	string
`tasks[].notes`	string
`tasks[].status`	string	`open`, `done`, `archived`
`tasks[].priority`	integer	-9007199254740991 to 9007199254740991
`tasks[].when`	object		How the task is scheduled (distinct from its `deadline`).
`tasks[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`tasks[].when.date`	string (optional)
`tasks[].when.hasTime`	boolean (optional)
`tasks[].when.time`	string \| null (optional)
`tasks[].deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`tasks[].projectId`	string \| null
`tasks[].areaId`	string \| null
`tasks[].headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`tasks[].tags`	string[]
`tasks[].checklist`	object[]
`tasks[].checklist[].id`	string
`tasks[].checklist[].label`	string
`tasks[].checklist[].done`	boolean
`tasks[].completedAt`	number \| null
`tasks[].durationMin`	number \| null
`tasks[].kind`	string	`task`, `event`
`tasks[].repeat`	object \| null
`tasks[].repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	`day`, `week`, `month`, `year`
`tasks[].repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`tasks[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`tasks[].notePath`	string \| null	0 to 1024 characters
`tasks[].conversationPath`	string \| null	0 to 1024 characters
`tasks[].assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`tasks[].assignee`	object \| null		The same person, as the row draws them.
`tasks[].assignee.id`	string
`tasks[].assignee.username`	string \| null
`tasks[].assignee.name`	string \| null
`tasks[].assignee.email`	string \| null
`tasks[].assignee.image`	string \| null
`tasks[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.
`projects`	object[]
`projects[].id`	string
`projects[].name`	string
`projects[].areaId`	string \| null
`projects[].status`	string	`active`, `done`, `archived`
`projects[].deadline`	string \| null
`projects[].notes`	string
`projects[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`projects[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this project.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reorder_hierarchy",
    "arguments": {
      "moves": [
        {
          "kind": "task",
          "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "order": 0,
          "parent": {
            "kind": "root"
          }
        }
      ],
      "workspaceId": "21a3230e-0377-4a58-8ff1-b3709a9e2328"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 2 hierarchy item(s) moved."
      }
    ],
    "structuredContent": {
      "tasks": [
        {
          "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "notes": "Notes for the Acme launch.",
          "status": "open",
          "priority": 2,
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "tags": ["acme"],
          "checklist": [
            {
              "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
              "label": "Acme",
              "done": true
            }
          ],
          "completedAt": 1790069400000,
          "durationMin": 30,
          "kind": "task",
          "repeat": {
            "every": 3,
            "unit": "day",
            "mode": "calendar"
          },
          "visibility": "public",
          "order": 0,
          "notePath": "Acme/Weekly review",
          "conversationPath": "Acme/Weekly review",
          "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "assignee": {
            "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "username": "ada",
            "name": "Acme",
            "email": "ada@acme.example",
            "image": "https://acme.example/ada.png"
          },
          "accessRole": "owner"
        }
      ],
      "projects": [
        {
          "id": "244210e4-8437-4655-8980-a70249a99369",
          "name": "Acme",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "status": "active",
          "deadline": "2026-09-22",
          "notes": "Notes for the Acme launch.",
          "order": 0,
          "accessRole": "owner"
        }
      ]
    }
  }
}

doers tasks reorder --workspace-id 21a3230e-0377-4a58-8ff1-b3709a9e2328
# moves: structured argument(s) the CLI cannot pass as flags.

schedule_tasks

Schedule tasks atomically. Schedules one or more tasks by day, optional precise time and optional manual order in one transaction. Omitted time preserves an existing precise time; null clears it. If any task is inaccessible, nothing changes. Deadlines are never changed.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/tasks/schedule`
CLI	`doers tasks schedule`
Touches	`areas`, `projects`, `tasks`
Operation	`scheduleTasks`

Input

Field	Type	Required	Allowed values	Description
`items`	object[]	yes	at most 50 items	No description in the registry.
`items[].taskId`	string	yes	UUID	Identifier of a row.
`items[].day`	string	yes	`YYYY-MM-DD`	Local day key, `YYYY-MM-DD`.
`items[].time`	string \| null	no	`HH:MM`	No description in the registry.
`items[].order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`tasks`	object[]
`tasks[].id`	string
`tasks[].title`	string
`tasks[].notes`	string
`tasks[].status`	string	`open`, `done`, `archived`
`tasks[].priority`	integer	-9007199254740991 to 9007199254740991
`tasks[].when`	object		How the task is scheduled (distinct from its `deadline`).
`tasks[].when.kind`	string	`today`, `anytime`, `someday`, `date`
`tasks[].when.date`	string (optional)
`tasks[].when.hasTime`	boolean (optional)
`tasks[].when.time`	string \| null (optional)
`tasks[].deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`tasks[].projectId`	string \| null
`tasks[].areaId`	string \| null
`tasks[].headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`tasks[].tags`	string[]
`tasks[].checklist`	object[]
`tasks[].checklist[].id`	string
`tasks[].checklist[].label`	string
`tasks[].checklist[].done`	boolean
`tasks[].completedAt`	number \| null
`tasks[].durationMin`	number \| null
`tasks[].kind`	string	`task`, `event`
`tasks[].repeat`	object \| null
`tasks[].repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`tasks[].repeat.unit`	string	`day`, `week`, `month`, `year`
`tasks[].repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`tasks[].repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`tasks[].visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`tasks[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`tasks[].notePath`	string \| null	0 to 1024 characters
`tasks[].conversationPath`	string \| null	0 to 1024 characters
`tasks[].assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`tasks[].assignee`	object \| null		The same person, as the row draws them.
`tasks[].assignee.id`	string
`tasks[].assignee.username`	string \| null
`tasks[].assignee.name`	string \| null
`tasks[].assignee.email`	string \| null
`tasks[].assignee.image`	string \| null
`tasks[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "schedule_tasks",
    "arguments": {
      "items": [
        {
          "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "day": "2026-09-22"
        }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 1 task(s) scheduled."
      }
    ],
    "structuredContent": {
      "tasks": [
        {
          "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
          "title": "Prepare the Acme quarterly review",
          "notes": "Notes for the Acme launch.",
          "status": "open",
          "priority": 2,
          "when": {
            "kind": "today"
          },
          "deadline": "2026-09-22",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "tags": ["acme"],
          "checklist": [
            {
              "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
              "label": "Acme",
              "done": true
            }
          ],
          "completedAt": 1790069400000,
          "durationMin": 30,
          "kind": "task",
          "repeat": {
            "every": 3,
            "unit": "day",
            "mode": "calendar"
          },
          "visibility": "public",
          "order": 0,
          "notePath": "Acme/Weekly review",
          "conversationPath": "Acme/Weekly review",
          "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "assignee": {
            "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
            "username": "ada",
            "name": "Acme",
            "email": "ada@acme.example",
            "image": "https://acme.example/ada.png"
          },
          "accessRole": "owner"
        }
      ]
    }
  }
}

doers tasks schedule
# items: structured argument(s) the CLI cannot pass as flags.

set_checklist

Replace a task’s checklist. Replaces the whole list, in the order given. This is what an editor saves: the app lets someone rename, reorder and delete items in one pass, and sending that as a series of adds and ticks could not express a removal at all. An item keeping its id keeps its identity; one without gets a new id.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PUT https://api.doers.sh/v2/tasks/{taskId}/checklist`
CLI	`doers tasks checklist-set`
Touches	`checklistItems`
Operation	`setChecklist`

Input

Field	Type	Required	Default	Allowed values	Description
`taskId` (path)	string	yes		UUID	Identifier of a row.
`checklist`	object[]	yes		at most 30 items	No description in the registry.
`checklist[].id`	string	no			Omit for a new item.
`checklist[].label`	string	yes		1 to 300 characters	No description in the registry.
`checklist[].done`	boolean	no	`false`		No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`checklist`	object[]
`checklist[].id`	string
`checklist[].label`	string
`checklist[].done`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_checklist",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "checklist": [
        {
          "label": "Acme"
        }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: checklist of 1 item(s) saved."
      }
    ],
    "structuredContent": {
      "checklist": [
        {
          "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
          "label": "Acme",
          "done": true
        }
      ]
    }
  }
}

doers tasks checklist-set 0ebb429f-a86d-481c-8630-fac53db1c91c
# checklist: structured argument(s) the CLI cannot pass as flags.

update_task

Update a task. Applies a partial patch: only the fields provided change. Passing null to deadline, projectId, areaId, notePath or conversationPath clears the value.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/tasks/{taskId}`
CLI	`doers tasks update`
Touches	`areas`, `projects`, `tasks`
Operation	`updateTask`

Input

Field	Type	Required	Allowed values	Description
`taskId` (path)	string	yes	UUID	Identifier of a row.
`title`	string	no	1 to 500 characters	No description in the registry.
`notes`	string	no	0 to 10000 characters	Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. Do not use code blocks (```) or images: the app’s editor does not support them and truncates the display from that point on.
`when`	string	no	`today`, `anytime`, `someday`; `YYYY-MM-DD`	Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.
`time`	string	no	`HH:MM`	Time `HH:MM`: only meaningful alongside a date.
`deadline`	string \| null	no	`YYYY-MM-DD`	No description in the registry.
`priority`	integer	no	0 to 4	0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.
`projectId`	string \| null	no	UUID	No description in the registry.
`areaId`	string \| null	no	UUID	No description in the registry.
`headingId`	string \| null	no	UUID	Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.
`tags`	string[]	no	at most 20 items	No description in the registry.
`durationMin`	integer \| null	no	15 to 1440	No description in the registry.
`notePath`	string \| null	no	0 to 1024 characters	No description in the registry.
`conversationPath`	string \| null	no	0 to 1024 characters	Atelier conversation carrying this delegated task; `null` un-delegates.
`done`	boolean	no		Shortcut for ticking or unticking.
`repeat`	object \| null	no		Repeat rule. `null` stops it repeating.
`repeat.every`	integer	yes	1 to 365	The multiplier: 2 × week.
`repeat.unit`	string	yes	`day`, `week`, `month`, `year`	No description in the registry.
`repeat.mode`	string	yes	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`repeat.weekdays`	integer[]	no	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`visibility`	string	no	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces. Defaults to private on create.
`order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`task`	object
`task.id`	string
`task.title`	string
`task.notes`	string
`task.status`	string	`open`, `done`, `archived`
`task.priority`	integer	-9007199254740991 to 9007199254740991
`task.when`	object		How the task is scheduled (distinct from its `deadline`).
`task.when.kind`	string	`today`, `anytime`, `someday`, `date`
`task.when.date`	string (optional)
`task.when.hasTime`	boolean (optional)
`task.when.time`	string \| null (optional)
`task.deadline`	string \| null		Due date `YYYY-MM-DD`, or `null`.
`task.projectId`	string \| null
`task.areaId`	string \| null
`task.headingId`	string \| null		Heading grouping the task, or `null` if it sits above them all.
`task.tags`	string[]
`task.checklist`	object[]
`task.checklist[].id`	string
`task.checklist[].label`	string
`task.checklist[].done`	boolean
`task.completedAt`	number \| null
`task.durationMin`	number \| null
`task.kind`	string	`task`, `event`
`task.repeat`	object \| null
`task.repeat.every`	integer	1 to 365	The multiplier: 2 × week.
`task.repeat.unit`	string	`day`, `week`, `month`, `year`
`task.repeat.mode`	string	`calendar`, `after`	`calendar`: the next one starts from the scheduled date. `after`: from ticking.
`task.repeat.weekdays`	integer[] (optional)	at most 7 items, each: 1 to 7	ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit “week”.
`task.visibility`	string	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.
`task.order`	number		Manual position. Fractional values are valid; lower sorts first.
`task.notePath`	string \| null	0 to 1024 characters
`task.conversationPath`	string \| null	0 to 1024 characters
`task.assigneeId`	string \| null		Who it is assigned to: one person who reaches the task, or nobody.
`task.assignee`	object \| null		The same person, as the row draws them.
`task.assignee.id`	string
`task.assignee.username`	string \| null
`task.assignee.name`	string \| null
`task.assignee.email`	string \| null
`task.assignee.image`	string \| null
`task.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this task.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_task",
    "arguments": {
      "taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "title": "Prepare the Acme quarterly review",
      "notes": "Notes for the Acme launch."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: task “Prepare the Acme quarterly review” updated."
      }
    ],
    "structuredContent": {
      "task": {
        "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
        "title": "Prepare the Acme quarterly review",
        "notes": "Notes for the Acme launch.",
        "status": "open",
        "priority": 2,
        "when": {
          "kind": "today"
        },
        "deadline": "2026-09-22",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "tags": ["acme"],
        "checklist": [
          {
            "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
            "label": "Acme",
            "done": true
          }
        ],
        "completedAt": 1790069400000,
        "durationMin": 30,
        "kind": "task",
        "repeat": {
          "every": 3,
          "unit": "day",
          "mode": "calendar"
        },
        "visibility": "public",
        "order": 0,
        "notePath": "Acme/Weekly review",
        "conversationPath": "Acme/Weekly review",
        "assigneeId": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
        "assignee": {
          "id": "53a9d65d-3627-4bc7-8170-af8d57e84d02",
          "username": "ada",
          "name": "Acme",
          "email": "ada@acme.example",
          "image": "https://acme.example/ada.png"
        },
        "accessRole": "owner"
      }
    }
  }
}

doers tasks update 0ebb429f-a86d-481c-8630-fac53db1c91c --title "Prepare the Acme quarterly review" --notes "Notes for the Acme launch."

update_tasks

Update several tasks at once. Applies the same patch to several tasks. Always prefer this as soon as two or more tasks receive the same change. The operation is atomic: if a single task is inaccessible, nothing changes. This is the reorganisation tool: projectId + headingId in one call files a whole batch under a milestone. Never fire a burst of update_task instead.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/tasks`
CLI	`doers tasks update-many`
Touches	`areas`, `projects`, `tasks`
Operation	`updateTasks`

Input

Field	Type	Required	Allowed values	Description
`taskIds`	string[]	yes	at most 50 items, each: UUID	Ids of the tasks concerned (50 maximum).
`when`	string	no	`today`, `anytime`, `someday`; `YYYY-MM-DD`	Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.
`time`	string	no	`HH:MM`	Time `HH:MM`: only meaningful alongside a date.
`deadline`	string \| null	no	`YYYY-MM-DD`	No description in the registry.
`priority`	integer	no	0 to 4	0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.
`projectId`	string \| null	no	UUID	No description in the registry.
`areaId`	string \| null	no	UUID	No description in the registry.
`headingId`	string \| null	no	UUID	Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.
`visibility`	string	no	`public`, `anonymized`, `private`	Who sees this task on shared and social surfaces. Defaults to private on create.

Output

Output fields

Field	Type	Allowed values	Description
`count`	integer	-9007199254740991 to 9007199254740991
`taskIds`	string[]

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_tasks",
    "arguments": {
      "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
      "when": "today",
      "time": "09:30"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: 3 task(s) updated."
      }
    ],
    "structuredContent": {
      "count": 3,
      "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
    }
  }
}

doers tasks update-many --task-ids 0ebb429f-a86d-481c-8630-fac53db1c91c --when today --time 09:30

​get_task

​Input

​Output

​Example

​get_tasks

​Input

​Output

​Example

​list_inbox_history

​Input

​Output

​Example

​list_task_members

​Input

​Output

​Example

​list_tasks

​Input

​Output

​Example

​add_checklist_items

​Input

​Output

​Example

​archive_tasks

​Input

​Output

​Example

​assign_task

​Input

​Output

​Example

​check_checklist_items

​Input

​Output

​Example

​complete_tasks

​Input

​Output

​Example

​create_task

​Input

​Output

​Example

​create_tasks

​Input

​Output

​Example

​delete_task

​Input

​Output

​Example

​quick_add_task

​Input

​Output

​Example

​reorder_hierarchy

​Input

​Output

​Example

​schedule_tasks

​Input

​Output

​Example

​set_checklist

​Input

​Output

​Example

​update_task

​Input

​Output

​Example

​update_tasks

​Input

​Output

​Example

get_task

Input

Output

Example

get_tasks

Input

Output

Example

list_inbox_history

Input

Output

Example

list_task_members

Input

Output

Example

list_tasks

Input

Output

Example

add_checklist_items

Input

Output

Example

archive_tasks

Input

Output

Example

assign_task

Input

Output

Example

check_checklist_items

Input

Output

Example

complete_tasks

Input

Output

Example

create_task

Input

Output

Example

create_tasks

Input

Output

Example

delete_task

Input

Output

Example

quick_add_task

Input

Output

Example

reorder_hierarchy

Input

Output

Example

schedule_tasks

Input

Output

Example

set_checklist

Input

Output

Example

update_task

Input

Output

Example

update_tasks

Input

Output

Example