> ## 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.
# Areas
> Areas, the domains of life that hold projects.
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_areas) | List the areas | Read · idempotent · no outside service |
| [`archive_area`](#archive_area) | Archive or restore an area | Write · destructive · no outside service |
| [`create_area`](#create_area) | Create an area | Write · no outside service |
| [`delete_area`](#delete_area) | Delete an archived area for good | Write · destructive · idempotent · no outside service |
| [`update_area`](#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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_areas",
"arguments": {
"includeArchived": false,
"workspaceId": "21a3230e-0377-4a58-8ff1-b3709a9e2328"
}
}
}
```
```json Response theme={null}
{
"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"
}
]
}
}
}
```
```bash CLI theme={null}
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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "archive_area",
"arguments": {
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"restore": false
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_area",
"arguments": {
"name": "Acme",
"hue": 3,
"icon": "rocket"
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
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
| Field | Type | Allowed values | Description |
| ------------------ | ------- | ------------------------------------- | ----------- |
| `areaId` | string | | |
| `detachedProjects` | integer | -9007199254740991 to 9007199254740991 | |
| `detachedTasks` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "delete_area",
"arguments": {
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
}
}
}
```
```json Response theme={null}
{
"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
}
}
}
```
```bash CLI theme={null}
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 | Default | 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
| 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
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_area",
"arguments": {
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"name": "Acme",
"hue": 3
}
}
}
```
```json Response theme={null}
{
"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"
}
}
}
}
```
```bash CLI theme={null}
doers areas update 4a91ee5f-0106-42b3-8c11-c168352f0abf --name Acme --hue 3
```