> ## 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.
# Headings
> Headings that divide a project's tasks.
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_headings) | List the headings | Read · idempotent · no outside service |
| [`create_heading`](#create_heading) | Create a heading (or a milestone) | Write · no outside service |
| [`delete_heading`](#delete_heading) | Delete a heading | Write · destructive · idempotent · no outside service |
| [`update_heading`](#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 | Default | 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
| 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
```json Request theme={null}
{
"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"
}
}
}
```
```json Response theme={null}
{
"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
}
]
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_heading",
"arguments": {
"name": "",
"projectId": "244210e4-8437-4655-8980-a70249a99369"
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| --------------- | ------- | ------------------------------------- | ----------- |
| `headingId` | string | | |
| `releasedTasks` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "delete_heading",
"arguments": {
"headingId": "5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e"
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"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"
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
}
```
```bash CLI theme={null}
doers headings update 5e60ff5a-c0ec-4f50-8aa9-4ac8a754bc0e --name Acme --deadline 2026-09-22
```