Data model

Workspace (your personal one, or a team)
└── Area            a domain of life: "Clients", "Health"
    ├── Project     an outcome with an end: "Acme renewal"
    │   ├── Heading a group inside the project, optionally dated
    │   │   └── Task
    │   └── Task
    └── Task        a task can sit directly in an area
Task                or in neither: it is then unfiled

Tasks

The fields you will use most. The tool reference lists them all.

Field	Meaning
`title`, `notes`	the task and its Markdown notes
`status`	`open`, `done` or `archived`
`when`	when you plan to do it (below)
`deadline`	when it is due, `YYYY-MM-DD`, or `null`
`priority`	`0` none, `1` low, `2` medium, `3` high, `4` goal of the day
`projectId`, `areaId`	where it is filed: a project or an area, never both
`headingId`	the heading it sits under, in the same project or area
`checklist`	items with `id`, `label` and `done`
`repeat`	a repeat rule, or `null`
`kind`	`task`, or `event` for a calendar block
`durationMin`	the time it should take, in minutes
`tags`	free labels
`visibility`	`public`, `anonymized` or `private` (the default): what shared and social surfaces show
`assigneeId`	the one person it is assigned to, among those who can reach it
`accessRole`	your role on it: `owner`, `editor`, `commenter` or `reader`
`completedAt`	when it was ticked, in milliseconds since the epoch

`when` is not `deadline`

These are two independent fields, and confusing them is the most common mistake.

when is the plan: when you intend to do the task. On input it is today, anytime (shown as Later in the app), someday (Future) or a date YYYY-MM-DD, with an optional time in HH:MM that only means something next to a date. On output it is an object:
{ "kind": "today" } { "kind": "date", "date": "2026-09-24", "hasTime": true, "time": "14:00" }
deadline is the commitment: when it must be done. A task planned for Monday can be due Friday; a task due Friday can be planned for no particular day.

Both feed the priority score: the earlier of the two counts.

Project or area, never both

A task belongs to a project, to an area, or to neither. Send projectId and areaId together and the project wins: areaId is ignored. A project may itself belong to an area.

Calendar blocks

A task with kind: "event" is a block of time on the calendar, not a to-do. It is left out of list_tasks, of the context counters and of the priority ranking.

Repeating tasks

A repeat rule is { "every": 2, "unit": "week", "mode": "calendar", "weekdays": [1, 4] }:

Field	Values
`every`	1 to 365
`unit`	`day`, `week`, `month`, `year`
`mode`	`calendar`: the next one is counted from the scheduled date. `after`: from the day you tick it
`weekdays`	ISO weekdays, 1 for Monday to 7 for Sunday; only with `unit: "week"`

Repeating works as a chain. Ticking a repeating task marks it done, so it stays in your history, and creates the next occurrence at once, with the same order and a deadline moved by the same amount as its date. The next date is computed from the caller’s day (X-Doers-Today, or UTC).

Projects

name, notes, an optional areaId, an optional deadline, and a status: active, done or archived.

Areas

name, notes, an optional icon and colour hue (0 to 360), and archived.

Headings

A heading groups the tasks of a project or an area. With a deadline it acts as a milestone, and it reports how many of its tasks are open and done. Deleting a heading keeps its tasks: they move back to the top of their project or area.

Archive, then delete

Action	Reversible	What happens to what is inside
Archive a task	yes, `restore: true`
Archive a project	yes	its open tasks are archived too; restoring the project does not restore them
Archive an area	yes	its active projects, their open tasks and its own open tasks are archived
Delete a task, project or area	no	refused with `422 not_archived` unless it is archived first
Delete a project	no	its tasks lose their project and stay
Delete a heading	no	its tasks stay, moved to the top

Archiving a task needs the owner role; ticking or editing one needs editor. Every account has a personal workspace, and can own or join team workspaces. list_tasks reads your personal workspace unless you pass workspaceId. Tasks, projects and areas can also be shared with people one by one, each with a role: reader, commenter or editor. See Sharing and Workspaces.

Mentions

Assistants cite entities as [[task:ID|Title]], [[project:ID|Name]] or [[area:ID|Name]]: the app renders them as links.

Get started

Concepts

Tasks

`when` is not `deadline`

Project or area, never both

Calendar blocks

Repeating tasks

Projects

Areas

Headings

Archive, then delete

Mentions

​Tasks

​when is not deadline

​Project or area, never both

​Calendar blocks

​Repeating tasks

​Projects

​Areas

​Headings

​Archive, then delete

​Workspaces and sharing

​Mentions

Tasks

`when` is not `deadline`

Project or area, never both

Calendar blocks

Repeating tasks

Projects

Areas

Headings

Archive, then delete

Workspaces and sharing

Mentions