Tasks

Create, read, update, and delete tasks; page a list; search and batch-fetch. Subtasks use the same endpoints — no separate routes. Create one with POST /projects/lists/{listId}/tasks and parentTaskId (plus required title and dueDate). List them with POST /projects/tasks/search filtered by parentTaskId, or subtaskViewMode (collapsed | expanded with embedded subtasks[] | separate with parentTaskId / parentName). Update and delete use Update A Task Or Subtask and Delete A Task Or Subtask with the subtask id. Custom fields: definitions live in the Custom Fields V2 API (objectKey: "task", optional scopes of space | folder | list | workspace). Set values on Create/Update Task via customFields — keys omit the task. prefix (definition task.project_phase → { "project_phase": "discovery" }).

📄️Get Tasks

Pages tasks whose primary (home) list is this list. Use `limit` and query `searchAfter` from the previous response `searchAfter` (opaque base64url string). Prefer Search Tasks with `parentTaskId` / `subtaskViewMode` for subtask-focused views.

📄️Create Task

Creates a task in this list as its home list. `title` and `dueDate` are required. `dueDate` accepts ISO 8601 or a Unix timestamp string; responses return ISO 8601. Optional TipTap `body` — see [TipTap documentation](https://tiptap.dev/docs/editor/introduction). To create a **subtask**, set `parentTaskId`. Response is `{ 'task': { … } }` without embedded `subtasks`.

📄️Get A Task By ID

Fetches one task or subtask by id. Fields are returned under `task`. A subtask’s parent id is `task.properties.parentTaskId`. TipTap content is `task.properties.body`. `properties.statusGroup` is server-derived and read-only; a task is complete when it is `done`. The home list is `properties.primaryListId`. Embedded `subtasks` are not returned — use Search Tasks with `subtaskViewMode=expanded`.

📄️Update A Task Or Subtask

Updates a task or subtask by id (title, TipTap `body`, status, dates, assignees, priority, `parentTaskId`, custom fields, etc.). Response is `{ 'task': { … } }` without embedded `subtasks`.

📄️Delete A Task Or Subtask

Deletes a task or subtask by id. Response: `{ 'success': true, 'id': '<taskId>' }`. A second delete on the same id returns not found.

📄️Search Tasks

Searches tasks across the location with filters, sort, free-text `query`, and optional `subtaskViewMode`. Requires `limit`; pass body `searchAfter` from the previous response `searchAfter` (opaque base64url string) for the next page. Scope to lists with `listIds` (max 10) — do not send a separate `graph` filter when using `listIds`. Filter subtasks with `parentTaskId` (Tasks V2 locations only; otherwise 422). `subtaskViewMode=expanded` returns embedded `subtasks[]`; `separate` may include `parentName`. Neither field appears on Get/Create/Update/List/Batch. `total` is the hit count after filters and access scope.

📄️Fetch Tasks By IDs

Fetches multiple tasks by id in one call. Results are RBAC-filtered — inaccessible ids are omitted rather than erroring. Does not return embedded `subtasks`.