Areas

5 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_areas`	List the areas	Read · idempotent · no outside service
`archive_area`	Archive or restore an area	Write · destructive · no outside service
`create_area`	Create an area	Write · no outside service
`delete_area`	Delete an archived area for good	Write · destructive · idempotent · no outside service
`update_area`	Update an area	Write · idempotent · no outside service

list_areas

List the areas. Returns the spheres of life, in manual order. An area contains projects and can carry tasks directly.


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/areas`
CLI	`doers areas list`
Touches	`areas`, `projects`, `tasks`
Operation	`listAreas`

Input

Field	Type	Required	Default	Allowed values	Description
`includeArchived` (query)	boolean	no	`false`		No description in the registry.
`workspaceId` (query)	string	no		UUID	The workspace to read within; the personal one by default (T-D11).

Output

Output fields

Field	Type	Allowed values	Description
`areas`	object[]
`areas[].id`	string
`areas[].name`	string
`areas[].hue`	integer \| null	0 to 360
`areas[].icon`	string \| null		Phosphor icon name.
`areas[].notes`	string
`areas[].archived`	boolean
`areas[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`areas[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this area.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_areas",
    "arguments": {
      "includeArchived": false,
      "workspaceId": "21a3230e-0377-4a58-8ff1-b3709a9e2328"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [4a91ee5f-0106-42b3-8c11-c168352f0abf] Acme"
      }
    ],
    "structuredContent": {
      "areas": [
        {
          "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "name": "Acme",
          "hue": 3,
          "icon": "rocket",
          "notes": "Notes for the Acme launch.",
          "archived": true,
          "order": 0,
          "accessRole": "owner"
        }
      ]
    }
  }
}

doers areas list --include-archived false --workspace-id 21a3230e-0377-4a58-8ff1-b3709a9e2328

archive_area

Archive or restore an area. Archiving is reversible and cascades: the area’s active projects, their open tasks, then the open tasks attached directly to the area.


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/areas/{areaId}/archive`
CLI	`doers areas archive`
Touches	`areas`, `projects`, `tasks`
Operation	`archiveArea`

Input

Field	Type	Required	Default	Allowed values	Description
`areaId` (path)	string	yes		UUID	Identifier of a row.
`restore`	boolean	no	`false`		No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`area`	object
`area.id`	string
`area.name`	string
`area.hue`	integer \| null	0 to 360
`area.icon`	string \| null		Phosphor icon name.
`area.notes`	string
`area.archived`	boolean
`area.order`	number		Manual position. Fractional values are valid; lower sorts first.
`area.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this area.
`archivedProjects`	integer	-9007199254740991 to 9007199254740991
`archivedTasks`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "archive_area",
    "arguments": {
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
      "restore": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: area archived with 3 project(s) and 3 task(s)."
      }
    ],
    "structuredContent": {
      "area": {
        "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "name": "Acme",
        "hue": 3,
        "icon": "rocket",
        "notes": "Notes for the Acme launch.",
        "archived": true,
        "order": 0,
        "accessRole": "owner"
      },
      "archivedProjects": 3,
      "archivedTasks": 3
    }
  }
}

doers areas archive 4a91ee5f-0106-42b3-8c11-c168352f0abf --restore false

create_area

Create an area. Creates a sphere of life.


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/areas`
CLI	`doers areas create`
Touches	`areas`, `projects`, `tasks`
Operation	`createArea`

Input

Field	Type	Required	Allowed values	Description
`workspaceId`	string	no	UUID	Where to file it: the personal workspace by default, or a team workspace the caller sits in.
`name`	string	yes	1 to 200 characters	No description in the registry.
`hue`	integer \| null	no	0 to 360	No description in the registry.
`icon`	string \| null	no	1 to 60 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.

Output

Output fields

Field	Type	Allowed values	Description
`area`	object
`area.id`	string
`area.name`	string
`area.hue`	integer \| null	0 to 360
`area.icon`	string \| null		Phosphor icon name.
`area.notes`	string
`area.archived`	boolean
`area.order`	number		Manual position. Fractional values are valid; lower sorts first.
`area.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this area.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_area",
    "arguments": {
      "name": "Acme",
      "hue": 3,
      "icon": "rocket"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: area “Acme” created [4a91ee5f-0106-42b3-8c11-c168352f0abf]."
      }
    ],
    "structuredContent": {
      "area": {
        "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "name": "Acme",
        "hue": 3,
        "icon": "rocket",
        "notes": "Notes for the Acme launch.",
        "archived": true,
        "order": 0,
        "accessRole": "owner"
      }
    }
  }
}

doers areas create Acme --hue 3 --icon rocket

delete_area

Delete an archived area for good. Removes an area permanently. The area must already be archived: the irreversible step is deliberately reachable only from the reversible one, so nothing is lost by a single misplaced call. Its projects and tasks are detached, never deleted: they lose their area and stay. An area groups, it does not contain.


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/areas/{areaId}`
CLI	`doers areas delete`
Touches	`areas`, `projects`, `tasks`
Operation	`deleteArea`

Input

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

Output

Output fields

Field	Type	Allowed values
`areaId`	string
`detachedProjects`	integer	-9007199254740991 to 9007199254740991
`detachedTasks`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_area",
    "arguments": {
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: area deleted. 3 project(s) and 3 task(s) kept, without an area."
      }
    ],
    "structuredContent": {
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
      "detachedProjects": 3,
      "detachedTasks": 3
    }
  }
}

doers areas delete 4a91ee5f-0106-42b3-8c11-c168352f0abf

update_area

Update an area. Partial patch: name, anodized hue, icon (a Phosphor icon name) or notes.


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/areas/{areaId}`
CLI	`doers areas update`
Touches	`areas`, `projects`, `tasks`
Operation	`updateArea`

Input

Field	Type	Required	Allowed values	Description
`areaId` (path)	string	yes	UUID	Identifier of a row.
`name`	string	no	1 to 200 characters	No description in the registry.
`hue`	integer \| null	no	0 to 360	No description in the registry.
`icon`	string \| null	no	1 to 60 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.
`order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`area`	object
`area.id`	string
`area.name`	string
`area.hue`	integer \| null	0 to 360
`area.icon`	string \| null		Phosphor icon name.
`area.notes`	string
`area.archived`	boolean
`area.order`	number		Manual position. Fractional values are valid; lower sorts first.
`area.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this area.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_area",
    "arguments": {
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
      "name": "Acme",
      "hue": 3
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: area “Acme” updated."
      }
    ],
    "structuredContent": {
      "area": {
        "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "name": "Acme",
        "hue": 3,
        "icon": "rocket",
        "notes": "Notes for the Acme launch.",
        "archived": true,
        "order": 0,
        "accessRole": "owner"
      }
    }
  }
}

doers areas update 4a91ee5f-0106-42b3-8c11-c168352f0abf --name Acme --hue 3

MCP server

Tool reference

list_areas

Input

Output

Example

archive_area

Input

Output

Example

create_area

Input

Output

Example

delete_area

Input

Output

Example

update_area

Input

Output

Example

​list_areas

​Input

​Output

​Example

​archive_area

​Input

​Output

​Example

​create_area

​Input

​Output

​Example

​delete_area

​Input

​Output

​Example

​update_area

​Input

​Output

​Example

list_areas

Input

Output

Example

archive_area

Input

Output

Example

create_area

Input

Output

Example

delete_area

Input

Output

Example

update_area

Input

Output

Example