Headings

4 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
`list_headings`	List the headings	Read · idempotent · no outside service
`create_heading`	Create a heading (or a milestone)	Write · no outside service
`delete_heading`	Delete a heading	Write · destructive · idempotent · no outside service
`update_heading`	Update a heading	Write · idempotent · no outside service

list_headings

List the headings. Returns the headings of a project or an area, in display order, with the number of open and completed tasks under each. A heading carrying a deadline is a milestone: the same object, dated. Call this before any reorganisation, to see what already exists.


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/headings`
CLI	`doers headings list`
Touches	`headings`, `tasks`
Operation	`listHeadings`

Input

Field	Type	Required	Allowed values	Description
`projectId` (query)	string	no	UUID	Identifier of a row.
`areaId` (query)	string	no	UUID	Identifier of a row.
`workspaceId` (query)	string	no	UUID	The workspace to read within; the personal one by default (T-D11).

Output

Output fields

Field	Type	Allowed values	Description
`headings`	object[]
`headings[].id`	string
`headings[].name`	string
`headings[].projectId`	string \| null
`headings[].areaId`	string \| null
`headings[].deadline`	string \| null		Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping.
`headings[].notes`	string
`headings[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`headings[].openTaskCount`	integer	-9007199254740991 to 9007199254740991
`headings[].doneTaskCount`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_headings",
    "arguments": {
      "projectId": "244210e4-8437-4655-8980-a70249a99369",
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e] Acme → 2026-09-22 · 3/6 done"
      }
    ],
    "structuredContent": {
      "headings": [
        {
          "id": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
          "name": "Acme",
          "projectId": "244210e4-8437-4655-8980-a70249a99369",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "deadline": "2026-09-22",
          "notes": "Notes for the Acme launch.",
          "order": 0,
          "openTaskCount": 3,
          "doneTaskCount": 3
        }
      ]
    }
  }
}

doers headings list --project-id 244210e4-8437-4655-8980-a70249a99369 --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf

create_heading

Create a heading (or a milestone). Creates a grouping of tasks under a project or under an area: never both. Provide deadline to make it a dated milestone; leave it out for a plain grouping. The heading is appended last. File tasks into it afterwards with update_tasks and its headingId field: one call for a whole batch.


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/headings`
CLI	`doers headings create`
Touches	`headings`, `tasks`
Operation	`createHeading`

Input

Field	Type	Required	Default	Allowed values	Description
`name`	string	no	`""`	0 to 200 characters	No description in the registry.
`projectId`	string \| null	no		UUID	No description in the registry.
`areaId`	string \| null	no		UUID	No description in the registry.
`deadline`	string \| null	no		`YYYY-MM-DD`	Milestone due date. Absent means a plain grouping.
`notes`	string \| null	no		0 to 10000 characters	No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`heading`	object
`heading.id`	string
`heading.name`	string
`heading.projectId`	string \| null
`heading.areaId`	string \| null
`heading.deadline`	string \| null		Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping.
`heading.notes`	string
`heading.order`	number		Manual position. Fractional values are valid; lower sorts first.
`heading.openTaskCount`	integer	-9007199254740991 to 9007199254740991
`heading.doneTaskCount`	integer	-9007199254740991 to 9007199254740991

Example

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: heading “Acme” created [5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e]: milestone on 2026-09-22."
      }
    ],
    "structuredContent": {
      "heading": {
        "id": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "name": "Acme",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "deadline": "2026-09-22",
        "notes": "Notes for the Acme launch.",
        "order": 0,
        "openTaskCount": 3,
        "doneTaskCount": 3
      }
    }
  }
}

doers headings create "" --project-id 244210e4-8437-4655-8980-a70249a99369

delete_heading

Delete a heading. Removes the grouping without touching the tasks: they move up to the top of their project or area. A heading groups, it does not contain: removing one must never make work disappear. Unlike tasks, projects and areas, this deletion is not reversible: the grouping is lost, only the tasks’ attachment is preserved.


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/headings/{headingId}`
CLI	`doers headings delete`
Touches	`headings`, `tasks`
Operation	`deleteHeading`

Input

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

Output

Output fields

Field	Type	Allowed values	Description
`headingId`	string
`releasedTasks`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_heading",
    "arguments": {
      "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: heading deleted, 3 task(s) moved to the top (none lost)."
      }
    ],
    "structuredContent": {
      "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
      "releasedTasks": 3
    }
  }
}

doers headings delete 5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e

update_heading

Update a heading. Partial patch: name, deadline, description, position. deadline: null removes the due date and the heading becomes a plain grouping again. The parent does not change here: a heading moved to another project would leave its tasks attached to a grouping invisible from their own page. To move a batch, create the heading in the right parent then call update_tasks with projectId and headingId.


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/headings/{headingId}`
CLI	`doers headings update`
Touches	`headings`, `tasks`
Operation	`updateHeading`

Input

Field	Type	Required	Allowed values	Description
`headingId` (path)	string	yes	UUID	Identifier of a row.
`name`	string	no	1 to 200 characters	No description in the registry.
`deadline`	string \| null	no	`YYYY-MM-DD`	No description in the registry.
`notes`	string \| null	no	0 to 10000 characters	No description in the registry.
`order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`heading`	object
`heading.id`	string
`heading.name`	string
`heading.projectId`	string \| null
`heading.areaId`	string \| null
`heading.deadline`	string \| null		Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping.
`heading.notes`	string
`heading.order`	number		Manual position. Fractional values are valid; lower sorts first.
`heading.openTaskCount`	integer	-9007199254740991 to 9007199254740991
`heading.doneTaskCount`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_heading",
    "arguments": {
      "headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
      "name": "Acme",
      "deadline": "2026-09-22"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: heading “Acme” updated."
      }
    ],
    "structuredContent": {
      "heading": {
        "id": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e",
        "name": "Acme",
        "projectId": "244210e4-8437-4655-8980-a70249a99369",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "deadline": "2026-09-22",
        "notes": "Notes for the Acme launch.",
        "order": 0,
        "openTaskCount": 3,
        "doneTaskCount": 3
      }
    }
  }
}

doers headings update 5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e --name Acme --deadline 2026-09-22

MCP server

Tool reference

list_headings

Input

Output

Example

create_heading

Input

Output

Example

delete_heading

Input

Output

Example

update_heading

Input

Output

Example

​list_headings

​Input

​Output

​Example

​create_heading

​Input

​Output

​Example

​delete_heading

​Input

​Output

​Example

​update_heading

​Input

​Output

​Example

list_headings

Input

Output

Example

create_heading

Input

Output

Example

delete_heading

Input

Output

Example

update_heading

Input

Output

Example