Skip to main content

Tasks

Task CRUD, reordering, and approval

📄️List tasks for a project

List tasks for a project. When called without query params, returns the full task list (with relations). Requires `tasks.read`. Pass `?fields=minimal` to receive only `id`, `title`, `taskNumber`, and `taskKey` (used for gate criterion linking and MCP key resolution) — that mode accepts full-scope `tasks.read`, `gates.create`, or `gates.update`. The `.own` scope on `tasks.read` does NOT grant access here, since minimal mode returns every task in the project regardless of ownership.

📄️PT-448 cross-project 'goal' view

PT-448 cross-project 'goal' view. Lists every task carrying any of the requested `labels` across the projects the caller can read (tenant-scoped). Requires full `tasks.read` (the list is not ownership-scoped, so `tasks.read.own` is rejected) AND `projects.read` (or `.own`) plus an active membership. A GUEST member or a `projects.read.own`-only caller is restricted to collaborator/creator projects. Tasks in projects the caller cannot read are omitted; cross-project dependency references are redacted (taskKey + projectId omitted, title + status replaced with sentinels, isCrossProject=true) per the PT-283 precedent, so the real key/title never leak. Each row carries project, key, title, status, priority, and `isBlocked`/`isBlocking` flags; sorted by priority (URGENT first), task key as tiebreak. Capped at the 500 highest-priority rows; `truncated` is true when more match.

📄️PT-482 label suggestions

PT-482 label suggestions. Returns the distinct labels in use for the tenant (optionally narrowed to one project), most-used first, as the autocomplete vocabulary behind the Jira-style label combobox. Tenant-scoped; the response is non-sensitive autocomplete strings, never task content — so the gate is lighter than the goal view: an active member who can read OR create tasks. Any scope satisfies it — full `tasks.read` / `tasks.create` or the `.own`-scoped variants (`tasks.read.own` / `tasks.create.own`).

📄️PT-491 cross-project epic-children listing

PT-491 cross-project epic-children listing. Lists every task whose `epicId` points at the given EPIC, across every project in the tenant (the `epicId` edge is tenant-scoped as of PT-446), PLUS the subtasks (`parentTaskId`) of those readable children so the Child Issues panel can render a nested task → subtask tree (PT-528). The project-scoped `GET /api/projects/:id/tasks?epicId=` filter is unchanged and only returns children in that one project — this route is its cross-project complement. Requires full `tasks.read` (the list is not ownership-scoped) AND `projects.read` (or `.own`) plus an active membership. Envelope: the caller must be able to read the EPIC itself — a non-existent, cross-tenant, or unreadable-project epic all return 403 (no existence oracle); a readable non-EPIC target returns 400. Children in projects the caller cannot read are redacted to an opaque id + the PT-283 sentinels (taskKey/projectId/issueType/progress dropped, title/status sentinelled, isCrossProject=true), so the real key/title never leak. Only a full org-wide `projects.read` holder sees every child un-redacted. Readable rows also carry `parentTaskId` (PT-528); a parent edge is nulled when its parent is unreadable, and a subtask of an unreadable child — or one in a project the caller cannot read — is omitted, so no cross-project parent–child relationship leaks.

📄️PT-431 task velocity

PT-431 task velocity. Returns completed-tasks-per-week buckets over the trailing `weeks` window (default 12, clamped to [1, 52]), the data source for the dashboard Task Velocity widget. A completion is a task whose `completedAt` (stamped when it transitions into a project-configured completed status) falls in the window. Weeks are ISO-8601 (Monday 00:00 UTC). Requires `tasks.read | tasks.read.own` AND `projects.read | projects.read.own` plus an active membership. A `tasks.read.own` caller counts only their own completions; a GUEST / `projects.read.own` caller is restricted to collaborator/creator projects. Archived (COMPLETED / CANCELLED) projects are excluded.

📄️Create a typed lateral link from the source task ([taskId]) to another task in the same project

Create a typed lateral link from the source task ([taskId]) to another task in the same project. The body either links an existing task (`{ targetTaskId, linkType }`) or creates a new follow-up task and links it (`{ newTaskTitle, linkType }`, status BACKLOG or the project default, reporter = caller — PT-479). Supported link types: BLOCKS | RELATES | DUPLICATES | CLONES | CAUSES | FOLLOWS. Both tasks must be in the same project. The create-new branch also requires `tasks.create`.

📄️Apply a sparse field patch to up to 100 tasks in a single transaction

Apply a sparse field patch to up to 100 tasks in a single transaction. The patch accepts any non-empty subset of status, assigneeId, dueDate, and priority — at least one field must be present, otherwise the request is rejected with 400. Fields left out are untouched on every selected task. All-or-nothing semantics: if any task in the batch fails validation or update, the whole batch rolls back. Status values are validated per task's project — a status name missing from any selected task's project rejects the batch.