> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doers.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Tasks
> Create, read, schedule, tick and archive tasks.
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_task) | Get a task | Read · idempotent · no outside service |
| [`get_tasks`](#get_tasks) | Get several tasks by id | Read · idempotent · no outside service |
| [`list_inbox_history`](#list_inbox_history) | Tasks you have already triaged | Read · idempotent · no outside service |
| [`list_task_members`](#list_task_members) | List the people with access to a task | Read · idempotent · no outside service |
| [`list_tasks`](#list_tasks) | List the tasks | Read · idempotent · no outside service |
| [`add_checklist_items`](#add_checklist_items) | Add checklist items | Write · no outside service |
| [`archive_tasks`](#archive_tasks) | Archive or restore tasks | Write · destructive · no outside service |
| [`assign_task`](#assign_task) | Assign a task to someone, or to nobody | Write · idempotent · no outside service |
| [`check_checklist_items`](#check_checklist_items) | Tick checklist items | Write · idempotent · no outside service |
| [`complete_tasks`](#complete_tasks) | Tick or untick tasks | Write · no outside service |
| [`create_task`](#create_task) | Create a task | Write · no outside service |
| [`create_tasks`](#create_tasks) | Create several tasks atomically | Write · no outside service |
| [`delete_task`](#delete_task) | Delete an archived task for good | Write · destructive · idempotent · no outside service |
| [`quick_add_task`](#quick_add_task) | Create a task from natural language | Write · no outside service |
| [`reorder_hierarchy`](#reorder_hierarchy) | Move tasks and projects atomically | Write · idempotent · no outside service |
| [`schedule_tasks`](#schedule_tasks) | Schedule tasks atomically | Write · idempotent · no outside service |
| [`set_checklist`](#set_checklist) | Replace a task's checklist | Write · idempotent · no outside service |
| [`update_task`](#update_task) | Update a task | Write · idempotent · no outside service |
| [`update_tasks`](#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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_task",
"arguments": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_tasks",
"arguments": {
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
}
}
}
```
```json Response theme={null}
{
"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"]
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_inbox_history",
"arguments": {
"limit": 100,
"cursor": "Notes for the Acme launch."
}
}
}
```
```json Response theme={null}
{
"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."
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_task_members",
"arguments": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "- Acme (owner)"
}
],
"structuredContent": {
"members": [
{
"userId": "04f8996d-a763-47a9-89b1-028ee3007569",
"label": "Acme",
"role": "owner"
}
]
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_tasks",
"arguments": {
"status": "open",
"projectId": "244210e4-8437-4655-8980-a70249a99369"
}
}
}
```
```json Response theme={null}
{
"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."
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ------------------- | --------- | ------------------------------------- | ----------- |
| `checklist` | object\[] | | |
| `checklist[].id` | string | | |
| `checklist[].label` | string | | |
| `checklist[].done` | boolean | | |
| `added` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"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."]
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ---------- | ------- | ------------------------------------- | ----------- |
| `count` | integer | -9007199254740991 to 9007199254740991 | |
| `restored` | boolean | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "archive_tasks",
"arguments": {
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
"restore": false
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: 3 task(s) restored."
}
],
"structuredContent": {
"count": 3,
"restored": true
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "assign_task",
"arguments": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
"username": "ada"
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ------------------- | --------- | ------------------------------------- | ----------- |
| `checklist` | object\[] | | |
| `checklist[].id` | string | | |
| `checklist[].label` | string | | |
| `checklist[].done` | boolean | | |
| `changed` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"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
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ------- | ------- | ------------------------------------- | ----------- |
| `count` | integer | -9007199254740991 to 9007199254740991 | |
| `done` | boolean | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "complete_tasks",
"arguments": {
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
"done": true
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: 3 task(s) completed."
}
],
"structuredContent": {
"count": 3,
"done": true
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"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"
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_tasks",
"arguments": {
"tasks": [
{
"title": "Prepare the Acme quarterly review"
}
]
}
}
}
```
```json Response theme={null}
{
"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"
}
]
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| -------- | ------ | -------------- | ----------- |
| `taskId` | string | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "delete_task",
"arguments": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: task deleted for good."
}
],
"structuredContent": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c"
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"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"
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"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"
}
}
}
```
```json Response theme={null}
{
"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"
}
]
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "schedule_tasks",
"arguments": {
"items": [
{
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
"day": "2026-09-22"
}
]
}
}
}
```
```json Response theme={null}
{
"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"
}
]
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ------------------- | --------- | -------------- | ----------- |
| `checklist` | object\[] | | |
| `checklist[].id` | string | | |
| `checklist[].label` | string | | |
| `checklist[].done` | boolean | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "set_checklist",
"arguments": {
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
"checklist": [
{
"label": "Acme"
}
]
}
}
}
```
```json Response theme={null}
{
"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
}
]
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"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."
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| Field | Type | Allowed values | Description |
| --------- | --------- | ------------------------------------- | ----------- |
| `count` | integer | -9007199254740991 to 9007199254740991 | |
| `taskIds` | string\[] | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_tasks",
"arguments": {
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"],
"when": "today",
"time": "09:30"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: 3 task(s) updated."
}
],
"structuredContent": {
"count": 3,
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
}
}
}
```
```bash CLI theme={null}
doers tasks update-many --task-ids 0ebb429f-a86d-481c-8630-fac53db1c91c --when today --time 09:30
```