---
title: Venom Tasks API
description: Read and change your org's Venom Tasks issues, teams, workflows, projects, cycles, views and inbox over the console session, and follow changes live.
section: cloud
order: 245
audience: [builder, agent, user]
sources: [services/nodejs-cloud/app/tasks/api, services/nodejs-cloud/lib/tasks, services/nodejs-cloud/migrations/0123_tasks_core.sql, services/nodejs-cloud/migrations/0124_tasks_planning.sql, services/nodejs-cloud/migrations/0125_tasks_views_inbox.sql, docs/tasks.md]
features: [cloud.tasks]
---

Venom Tasks is an issue tracker inside Venom Cloud, sold as an add-on. Teams have their own issue numbers
(`ENG-123`), workflow states, labels and cycles. Projects and milestones group work across teams, and saved views
keep a filter, grouping and layout. Each member has an inbox. An issue's assignee is always a member. The work
itself can be delegated to an agent.

The `/tasks` app uses this JSON API under `/tasks/api`. It takes the console's session cookie, so a signed-in browser
or anything that holds that cookie can call it. Agents use the MCP endpoint instead of this API.

## Quick example

```bash
# From a signed-in browser session (the cookie is the console's).
curl -s -b "venom_cloud_session=…" https://cloud.usevenom.dev/tasks/api/teams

curl -s -b "venom_cloud_session=…" -H 'content-type: application/json' \
  -H 'origin: https://cloud.usevenom.dev' \
  -d '{"teamId":"ENG","title":"Retry the payment webhook","priority":2}' \
  https://cloud.usevenom.dev/tasks/api/issues
```

Wherever a path or body names an issue, its id or its identifier (`ENG-123`) both work. An identifier keeps working
after the issue moves to another team or the team's key changes. Teams are named by id or key.

## Access

| Who | Can |
|---|---|
| Signed out | nothing: `401 signed_out` (JSON, also from the proxy) |
| Signed in, not a member of an org | nothing: `403 no_workspace` |
| The operator, also a member of an org | that org's workspace, with the role held there (the org Clerk had active at sign-in) |
| A member whose role lacks `org:manage` and `keys:write` (viewer, billing) | read |
| A member with `keys:write` (developer) | read, and create and change issues, comments, projects, cycles and views |
| A member with `org:manage` (owner, admin) | everything, including teams, workflow states and labels |

Writes (every method but GET) must come from the cloud's own origin, as console forms do.

Every route also checks the add-on. While billing is off, or the deployment has no `STRIPE_PRICE_TASKS_SEAT`, every
org has Tasks. Once the price is set, an org without the add-on gets `403 addon_required`, with `addon: "tasks"` and
`upgrade_url` in the error. `GET /tasks/api/addon` never checks the add-on, so the app can show the upgrade page.

## Endpoints

### Workspace

| Method and path | What |
|---|---|
| `GET /tasks/api/me` | the caller's uid, org, `canWrite`, `canManage` and teams |
| `GET /tasks/api/addon` | `{gate, active, status, currentPeriodEnd}`; `gate` is `billing_off`, `preview` or `sold` |
| `GET /tasks/api/members` | `{members, agents, people}`: the org's members and the agents that can be delegates |

### Teams, states and labels

| Method and path | What |
|---|---|
| `GET`, `POST /tasks/api/teams` | list the teams you can see (each with `parentId`, `private`, your `role` and `canManage`; `?addable=1` adds `addable`: org teams not in Tasks yet that you may add); create (`key`, `name`, `description`, `color`, `icon`, `triageEnabled`, `estimates`, `parentId` for a subteam, `private`), or `{orgTeamId}` to add an org team from Settings → Teams. A new team gets the default workflow: Triage, Backlog, Todo, In Progress, In Review, Done, Canceled, Duplicate |
| `GET`, `PATCH`, `DELETE /tasks/api/teams/{id}` | read with its states; change (the team's admins or Tasks managers; also `autoTriage`, `autoCloseParent`, `defaultTemplateId` (the members' default template), `defaultTemplateIdGuest` (the default for people outside the team; either may be a template of the team, a team above it or the workspace), `autoArchiveMonths` and `autoCloseMonths` (0, 1, 3, 6, 9 or 12), `defaultStateId`, `cycles`, `archived`, `parentId` (move under another team, or `null` for the top; see [Subteams](/docs/cloud/tasks-subteams)), `inheritEstimates`, `inheritCycles`; a new key keeps the old one as an alias); delete (refused while the team has subteams) |
| `GET`, `POST /tasks/api/teams/{id}/members` | list (with members of the teams above it: `inherited`, `via`); add `{memberId, role}` (`admin` or `member`; `lead` is read as `admin`; an agent id works too), as Settings → Teams allows |
| `DELETE /tasks/api/teams/{id}/members/{mid}` | remove |
| `GET`, `POST /tasks/api/teams/{id}/states` | list; add `{name, type, color, description}` |
| `POST /tasks/api/teams/{id}/states/reorder` | `{ids}` in the new order |
| `PATCH`, `DELETE /tasks/api/states/{id}` | change; delete with `?move_to=<state id>` when issues use it. The last state of a type cannot go |
| `GET`, `POST /tasks/api/labels` | org and team labels (`?team=`, `?includeArchived=1`); create `{name, color, teamId?, parentId?}` |
| `PATCH`, `DELETE /tasks/api/labels/{id}` | change; delete |
| `POST /tasks/api/import/plan`, `/run`, `/pull` | the importer: dry-run plan, create a batch of up to 25 issues, pull one page of a source API (see [Import issues](/docs/cloud/tasks-import)) |
| `GET`, `POST`, `PATCH`, `DELETE /tasks/api/label-groups[/{id}]` | label groups. An issue takes one label of each group |
| `GET`, `POST /tasks/api/teams/{id}/recurring` | the team's recurring issues; create one (`title`, `schedule`, plus optional `description`, `labelIds`, `assigneeId`, `priority`, `skipIfOpen`; see [Recurring issues](/docs/cloud/tasks-recurring)) |
| `GET`, `POST /tasks/api/issues/{id}/requests`, `/tasks/api/projects/{id}/requests`; `PATCH`, `DELETE /tasks/api/requests/{id}`; `GET /tasks/api/requests/sources` | customer requests: Support conversations, People companies and Funnel deals linked as requests, and what you may link (see [Customer requests](/docs/cloud/tasks-customer-requests)) |
| `GET`, `PUT /tasks/api/teams/{id}/sla` | the team's SLA settings `{teamId, sla: {rules, hours, riskPercent}}`; replace them (a team admin or `tasks:admin`), which recomputes the team's open issues and answers `recomputed` too (see [SLAs](/docs/cloud/tasks-sla)) |
| `GET`, `POST /tasks/api/teams/{id}/triage-rules` | the team's triage rules in the order they run; add one (`name`, `actions`, optional `filter` and `enabled`; see [Triage rules](/docs/cloud/tasks-triage-rules)) |
| `GET`, `PATCH`, `DELETE /tasks/api/triage-rules/{id}` | read; change (the same fields); delete |
| `POST /tasks/api/teams/{id}/triage-rules/reorder`, `/test` | set the order (`ids`); try a `filter` or a saved `ruleId` against the last 50 triage issues |
| `GET`, `PATCH`, `DELETE /tasks/api/recurring/{id}` | read; change (the same fields, plus `paused` to pause and resume); delete (the issues it made stay) |
| `GET`, `POST /tasks/api/teams/{id}/templates` | the templates the team offers (`?scope=team`, the default: its own, its parent teams' nearest first, then the workspace's; `workspace`: only the workspace's; `all`: every template you can see; each has `teamId`, null for a workspace template); create one (`name`, plus optional `title`, `description`, `labelIds`, `assigneeId`, `priority`, `stateId`, `projectId`, `estimate`, `delegateAgentId`, `subIssues`: a list of titles). Managers only for writes |
| `GET`, `POST /tasks/api/templates` | the workspace's templates (`?scope=all`: every template you can see); create a workspace template (owners and admins; the same fields without `stateId`, workspace labels only: a team's label or a status is `400 team_property` naming the field) |
| `GET`, `PATCH`, `DELETE /tasks/api/templates/{id}` | read; change (the same fields); delete (clears it as any team's default; issues made from it stay) |
| `POST /tasks/api/issues/{id}/apply-template` | `{ templateId, fields?, subIssues? }`: fill the issue's empty fields from the template (the title never changes, the description is added under a rule, labels are added, assignee, priority, project, estimate and agent only where empty) and make its sub-issues under it, in one transaction. `fields: false` or `subIssues: false` skips that part. A sub-issue refuses a template with sub-issues (`409 sub_issue_template`); another team's template is `400 wrong_team`. Answers `{ issue, created, skipped }` |

`estimates` is one of `none`, `exponential`, `fibonacci`, `linear` or `tshirt`. An estimate outside the team's
scale is refused. `cycles` is `{enabled, lengthWeeks, cooldownWeeks, startDay, upcoming, autoRollover, autoAddStarted, autoAddCompleted}` (see [Cycle automation](/docs/cloud/tasks-planning#cycle-automation)).

### Issues

| Method and path | What |
|---|---|
| `GET /tasks/api/issues` | a filtered, grouped, paged list (query parameters below) |
| `POST /tasks/api/issues/query` | the same, with a full `filter` tree in the body |
| `POST /tasks/api/issues` | create (`teamId`, `title`, plus optional `description`, `stateId`, `triage`, `priority`, `estimate`, `assigneeId`, `delegateAgentId`, `labelIds`, `parentId`, `projectId`, `milestoneId`, `cycleId`, `dueDate`, `position`, `templateId`: the template's sub-issues are made under the new issue; someone outside the team who sends no `templateId` gets the team's `defaultTemplateIdGuest` for the fields they left out, `null` asks for none) |
| `POST /tasks/api/issues/batch` | `{ids, patch}`: one patch on up to 250 issues |
| `POST /tasks/api/issues/move` | Move to another team: `{ids, teamId, subIssues?, dryRun?}`, up to 50 issues (250 with their sub-issues), one transaction. Each gets the target team's next number and its old identifier keeps resolving. The status maps to the target's state of the same name, else the first of the same type; team labels to the target's label of the same name, else they are removed; the cycle is cleared; the estimate is cleared when the target's scale lacks it; the project is cleared when the target team is not one of its teams; an assignee or delegate who can't see the target team is cleared. Answers `{dryRun, moves[{issueId, from, to, state, labelsMapped, labelsRemoved, cycleCleared, estimateCleared, projectCleared, assigneeCleared, delegateCleared, viaParent}], issues}`; with `dryRun: true` nothing is written and `to` is null. A team the caller can't see is `404`. MCP: `tasks_issue_move` |
| `GET`, `PATCH`, `DELETE /tasks/api/issues/{id}` | read with its children, parent, relations, subscribers and `recurring` (the series that made it, or null); change (also `addLabelIds`, `removeLabelIds`, `archived`, and `teamId` to move it to another team by the rules of `POST /tasks/api/issues/move`; `snoozedUntil`, an ISO time ahead or `null`, hides a triage issue until then); delete. An issue carries its SLA as `slaRuleId`, `slaStartedAt`, `slaRiskAt`, `slaDueAt` and `slaBreachedAt` (all null without one), and its customer `demand` `{requests, customers, revenueMinor, currency}` (null without requests; also on every listed issue) |
| `POST /tasks/api/issues/{id}/triage` | `{action, stateId?, duplicateOf?, comment?}`: accept, decline or mark a triage issue as a duplicate |
| `GET`, `POST /tasks/api/issues/{id}/comments` | list; add `{body, parentId?}` |
| `POST`, `DELETE /tasks/api/issues/{id}/reactions` | add `{emoji}` to the description, or take yours back (`?emoji=`); answers the description's `reactions` (also in `GET /tasks/api/issues/{id}`) |
| `GET /tasks/api/issues/{id}/activity` | every change, newest first (`?cursor=`, `?limit=`) |
| `GET /tasks/api/issues/{id}/history` | earlier versions of the description |
| `POST /tasks/api/issues/{id}/history/{vid}/restore` | put a version back |
| `POST`, `DELETE /tasks/api/issues/{id}/subscribe` | follow or stop following. `POST` takes an optional `{ "uid" }` body and `DELETE` an optional `?uid=`: another member's subscription (it needs write access to the issue, the person must belong to the org, and for adding must be able to see the issue's team). Both answer `{ subscribed, subscribers }`, everyone following the issue after the change |
| `POST /tasks/api/issues/{id}/relations` | `{type, issueId}`, where `type` is `blocks`, `blocked_by`, `related`, `duplicate_of` or `duplicated_by` |
| `DELETE /tasks/api/relations/{id}` | remove a relation (both sides) |
| `GET /tasks/api/relations/blocking` | `{ids}`: the issues that block an open issue (neither archived), both ends visible to you; My issues' Focus grouping reads it |
| `POST /tasks/api/issues/{id}/duplicate` | Make a copy: `{title?, properties?, subIssues?, relations?, teamId?}`. A new issue in the team's default status, titled "Copy of …" unless `title` says otherwise, with the description; the properties (priority, assignee, delegate, labels, project, milestone, due date, and in the same team the estimate and cycle) unless `properties: false`; the open sub-issues one level deep (up to 50) with `subIssues: true`; blocks, blocked-by and related relations with `relations: true`. `teamId` copies it into another team, leaving that team's missing labels, the estimate and the cycle behind. Answers `201 {issue, subIssues, relations}`; the copy links back to the original (`created_from`). MCP: `tasks_issue_duplicate`, which takes an `idempotency_key` |
| `POST /tasks/api/issues/{id}/convert-to-project` | Convert to project: `{name?}`. In one transaction, a planned project named after the issue (its description, the assignee as lead, the issue's team), the issue's sub-issues moved into the project (no longer sub-issues, up to 250), and the issue put in the project and closed as done with a comment linking it. Answers `201 {project, issue, moved}`; the project links back to the issue (`created_from`). MCP: `tasks_issue_convert_to_project` |
| `PATCH`, `DELETE /tasks/api/comments/{id}` | edit or delete your comment |
| `POST`, `DELETE /tasks/api/comments/{id}/reactions` | `{emoji}` on, `?emoji=` off |
| `GET /tasks/api/search?q=` | full-text search over titles and descriptions; an identifier finds that issue first (`?team=`, `?limit=`) |

What happens when an issue changes:

- **Numbers.** Each team counts its own, with no gaps, even when many issues are created at once.
- **Timestamps.** Entering a started state sets `startedAt`. Entering a completed state sets `completedAt`. Going
  back to triage, backlog or unstarted clears them.
- **Activity.** Every changed field writes its own activity row, and so does each label added or removed.
- **Links.** A `[[ENG-12]]` link in a description relates the two issues. An `@[Name](member:<uid>)` mention notifies
  that member.
- **Collapsible sections.** A description or comment can fold a long log or prompt away. Write it the way the editor
  does, a folded callout with the content quoted under it:

  ```markdown
  > [!toggle]- Build log
  > The lines to fold,
  > each quoted.
  ```

  `[!toggle]+` starts it open. `<details><summary>Build log</summary> … </details>` renders the same way in comments
  and updates. Both nest up to three deep. A reader that doesn't know them, such as an older client or a plain
  markdown viewer, shows a quote with the summary line on top, so nothing is lost. Exports (CSV, Markdown copy, the
  workspace export) carry the text exactly as stored.
- **Position.** `position: {afterId?, beforeId?}` places the issue in the manual order.
- **Secrets.** Text that looks like a secret is refused with `422 secrets_found`.

### List query parameters

| Parameter | Meaning |
|---|---|
| `team` | team ids or keys |
| `state`, `stateType` | state ids; `triage`, `backlog`, `unstarted`, `started`, `completed`, `canceled` |
| `assignee` | member uids, `me`, or `none` |
| `delegate` | agent ids, or `none` |
| `label`, `project`, `cycle`, `milestone`, `parent` | ids (`cycle` also takes `current`, `next`, `previous`; `none` for no value) |
| `priority` | `0` none, `1` urgent, `2` high, `3` medium, `4` low |
| `sla` | `breached`, `atRisk`, `onTrack`, `met`, or `none` for issues without an SLA, at the time of the request |
| `q` | full-text search, ANDed with the rest |
| `filter` | a filter tree as JSON (below) |
| `view` | a saved view's id: its filter, and its order and grouping unless given here |
| `reverse`, `closedLast` | `1` or `true`: `reverse` puts the `orderBy` ordering the other way round, ties included (not for `manual`); `closedLast` puts completed and canceled issues last, the most recently closed first. A saved view's own display supplies them when you give none. In the JSON query: `descending`, `closedByRecency` |
| `orderBy` | `manual` (default), `priority`, `updated`, `created`, `dueDate`, `identifier`, `estimate`, `title`, `state` (workflow order), `assignee` and `delegate` (by id, none last), `started` and `completed` (most recent first, none last), `timeInStatus` (longest in its status first), `links` (most first), and `requests`, `customers`, `revenue` ([customer demand](/docs/cloud/tasks-customer-requests.md), most first) |
| `groupBy` | `none` (default), `state`, `stateType`, `assignee`, `delegate`, `priority`, `project`, `milestone`, `cycle`, `label`, `team`, `parent` |
| `includeArchived`, `archivedOnly`, `includeSubIssues` | `1` or `true` / `false` (sub-issues are included by default; `archivedOnly` lists only archived issues) |
| `subteams` | `0` or `false`: a `team` filter means that team only. By default it includes the team's subteams |
| `limit`, `cursor` | page size 1–250 (default 50); `nextCursor` from the last page |

A list parameter takes a comma list or repeats (`assignee=me,none` or `assignee=me&assignee=none`). The answer is
`{issues, total, nextCursor}`, plus `groups: [{key, count}]` when grouped. The counts cover the whole filtered set,
and the issues come in group order. A cursor only works for the query that made it (`400 invalid_cursor`).

A filter tree nests `{and: [...]}`, `{or: [...]}` and conditions `{field, op, value}`, four levels deep with at most
50 conditions; a top-level `and` doesn't count as a level, so the parts it joins may each be four deep. The fields are `team`, `state`, `stateType`, `assignee`, `delegate`, `creator`, `priority`,
`estimate`, `label`, `project`, `milestone`, `cycle`, `parent`, `dueDate`, `createdAt`, `updatedAt`, `completedAt`,
`startedAt`, `canceledAt`, `hasChildren` (has sub-issues that are not archived) and `hasReminder` (the caller has a
pending reminder on it; both `is` / `isNot` with `true` or `false`),
`title`, `subscriber`, `sla` (`is`, `isNot`, `in`, `notIn` with `breached`, `atRisk`, `onTrack`, `met`;
`isEmpty` for no SLA), `source` (where the issue came from: `app`, `api`, `agent`, `support`, `forms`, `github`, …),
`description`, `requests` and `customers` (numbers; no requests is empty) and `revenue` (deal value in major units;
`lt`, `lte`, `gt`, `gte`, `isEmpty`, `isNotEmpty`), the last three [customer demand](/docs/cloud/tasks-customer-requests.md) as the
caller sees it. The operators are `is`, `isNot`, `in`, `notIn`, `isEmpty`, `isNotEmpty`, `lt`, `lte`,
`gt`, `gte`, `before`, `after`, `contains` and `notContains`. Dates take `YYYY-MM-DD`, an ISO time, or `-7d` /
`+2w` / `-1m` from now. `priority lt 3` means more urgent than medium, and no priority counts as the least urgent.

The advanced fields:

| Field | Values and operators |
|---|---|
| `relation` | `is`, `isNot`, `in`, `notIn` with `blocking`, `blockedBy`, `related`, `duplicate` (others are marked duplicates of it), `duplicateOf` (it is a duplicate), `parent` (it is a sub-issue), `child` (it has sub-issues), `any` (any blocking, blocked-by, related or duplicate relation) |
| `blockedBy` | issue ids: the issues blocking it; `isEmpty` is blocked by nothing |
| `timeInStatus` | `gt`, `gte`, `lt`, `lte` with a duration `12h`, `3d`, `2w`, `1m` (30 days): how long it has been in its current status (since it last changed status, else since its latest stamp) |
| `link` | its links' sources: `github`, `gitlab`, `bitbucket`, `figma`, `sentry`, `notion`, `jira`, `slack`, `loom`, `google`, `youtube`, `zendesk`, `intercom`, `linear` (the domain and its subdomains), `note`, or the host without `www.`; `isEmpty` is no links. "Includes all of" is an `and` of one `is` per source |
| `pullRequest` | `open`, `draft`, `merged`, `closed` (commits are not pull requests); `isEmpty` is no pull request |
| `projectStatus`, `projectPriority`, `projectLead`, `projectLabel` | the issue's project's status (`backlog`, `planned`, `started`, `paused`, `completed`, `canceled`), priority (as `priority`, comparisons too), lead (a member or `me`) and labels; empty when the issue has no project |
| `initiative` | initiative ids: the initiatives its project is in; `isEmpty` is none |
| `template` | template ids: the template it was created from (recorded for issues created since 2026-11-15) |
| `addedToCycle` | `planned` (it joined its cycle before the cycle started or within its first 24 hours, UTC) or `afterStart`; issues without a cycle match neither |
| `mentions` | `<kind>:<id>` references (`project:<uuid>`, `note:<uuid>`, `person:<uuid>`, …): the items the issue's description or comments mention; `isEmpty` is mentions nothing. "Includes all of" is an `and` of one `is` per reference |
| `agentChat` | `active` (starting or running), `done` (ready or ended), `failed`: the caller's own agent chats started from the issue, archived ones left out; another member's chats never count; `isEmpty` is no chat of yours |

Every field works the same in a list, a saved view, Insights (`filter=`) and the CSV export, and private
teams stay hidden: a project, initiative or relation condition never brings in an issue of a team you can't see.
So a client can evaluate these fields itself, an issue carries `relationTypes`, `blockedByIds`, `linkSources`,
`pullRequestStates`, `templateId` and `cycleAddedAt`, each left out when empty.

```json
{ "filter": { "and": [
  { "field": "assignee", "op": "is", "value": "me" },
  { "field": "dueDate", "op": "before", "value": "+7d" },
  { "or": [ { "field": "priority", "op": "lt", "value": 3 }, { "field": "label", "op": "in", "value": ["<label id>"] } ] }
] }, "groupBy": "state", "limit": 100 }
```

### Projects, milestones and cycles

| Method and path | What |
|---|---|
| `GET`, `POST /tasks/api/projects` | list (`?team=`, `?includeArchived=1`) with progress, counts and health, and per project `initiativeIds` (archived initiatives left out), `creatorId` and `milestoneCount`; create (`name`, `description`, `icon`, `color`, `status`, `lead`, `teamIds`, `startDate`, `targetDate`) |
| `GET`, `PATCH`, `DELETE /tasks/api/projects/{id}` | read with milestones; change (`teamIds` sets the teams you can see; a private team you are not in stays on the project); delete (its issues keep existing) |
| `POST /tasks/api/projects/{id}/move` | Move to another team: `{teamId, moveIssues?, dryRun?}`. The project's teams become `teamId` (teams you can't see stay). With `moveIssues: true` its issues in other teams move there too, by the issue move's rules, at most 100 per call: the answer `{dryRun, project, moves, remaining}` says how many are left, and calling again carries on. Milestones, updates, members and documents stay. MCP: `tasks_project_move` |
| `GET`, `POST /tasks/api/projects/{id}/updates` | status updates `{health, body, summaryHidden?}`; `health` is `on_track`, `at_risk` or `off_track`. `GET` answers `{updates[{…, editedAt, summary, summaryHidden, reactions, commentCount}], draftSummary, updateState, schedule}` ([Project updates](#project-updates)) |
| `GET`, `POST /tasks/api/issues/{id}/links`, `/tasks/api/projects/{id}/links` | links (`{id, kind: url \| note, url, host, title, noteId, noteTitle}`); add `{url, title?}`, or on a project `{noteId}` for an org-vault note |
| `PATCH`, `DELETE /tasks/api/links/{id}` | change `{title?, url?}` or remove a link |
| `POST /tasks/api/links/title` | `{url}` → `{title}`: the page title of a public https address (our server fetches it, no redirects, 4 s, 256 KB); `400` for a private or non-https address |
| `GET`, `POST /tasks/api/issues/{id}/attachments` | `{globe, attachments[{id, fileId, name, mime, size, url}]}`; `POST` multipart (field `file`, up to 4 MB) uploads and attaches. `globe: false` without the Notes add-on |
| `POST /tasks/api/issues/{id}/attachments/uploads` | `{name, mime?, size}` (up to 100 MB) → `{id, partBytes, parts}`; then `PUT …/uploads/{uploadId}?seq=n` per part and `POST …/uploads/{uploadId}` → `{attachment}` |
| `DELETE /tasks/api/attachments/{id}` | remove an attachment (the file stays in Notes) |
| `GET`, `POST`, `DELETE /tasks/api/projects/{id}/documents` | the project's Notes documents `{globe, canCreate, documents[{id, title, path, updatedAt, updatedBy}]}`; `POST {create: true, title?}` makes a note in `Projects/<name>/` of the org vault (needs `org:manage`), `POST {noteId}` links an org-vault note; `DELETE ?noteId=` detaches it. `globe: false` without the Notes add-on |
| `GET /tasks/api/milestones` | every milestone with a target date in the live projects (the timeline's markers) |
| `GET /tasks/api/projects/{id}/activity` | `{activity[{id, kind: created \| changed \| update \| milestone, actor, detail, createdAt}]}`, newest first (at most 200). A `changed` row's `detail` is `{field, from, to}` (or `{field, added, removed}` for members, labels and teams) |
| `GET`, `POST /tasks/api/projects/{id}/milestones` | list; add `{name, description?, targetDate?}` |
| `GET`, `POST`, `DELETE /tasks/api/projects/{id}/dependencies` | [project dependencies](/docs/cloud/tasks-planning.md#project-dependencies): `{blocking[], blockedBy[], hidden{blocking, blockedBy}}`, each end `{id, name, status, startDate, targetDate}` (ends you can't see are only counted in `hidden`); `POST {blocks}` or `{blockedBy}` (a project id) adds one, `409 dependency_cycle` when it would make a loop (the message names it); `DELETE ?blocks=` or `?blockedBy=` removes one. Both answer the new lists. Readers can list only |
| `GET /tasks/api/projects/dependencies` | every dependency whose ends you both see `{edges[{blockerId, blockedId}], hidden[{projectId, blocking, blockedBy}]}` (the timeline's lines) |
| `PATCH /tasks/api/projects/dates` | the timeline's drag in one transaction: `{projects[{id, startDate?, targetDate?}], milestones[{id, targetDate}]}` (at most 200 in all), each checked as its own `PATCH`; all or none. Answers `{projects}` |
| `GET`, `POST /tasks/api/initiatives` | list (`?includeArchived=1`) with `parentId`, `progress` and `health`, and `rollup` `{projects, total, byHealth{onTrack, atRisk, offTrack, none}}` over every sub-initiative (each project once; `projects` are the active ones: not archived, completed or canceled); create (`name`, `parentId`, `description`, `icon`, `color`, `status` (`proposed`, `planned`, `active`, `completed`, `canceled`), `owner`, `targetDate`, `projectIds`) |
| `GET`, `PATCH`, `DELETE /tasks/api/initiatives/{id}` | read with its own `projects`, `descendantProjects` (those of its sub-initiatives it does not group itself), `children` (its sub-initiatives with their roll-ups), `childProjects` (project ids under each child) and `ancestors` (the path above it, the top first); change (any create field, `parentId` null for the top, `projectIds` replaces the list, `archived`; `400 initiative_cycle` for a loop, `400 initiative_too_deep` past five levels); delete (its projects stay, its sub-initiatives move up one level) |
| `GET`, `POST /tasks/api/initiatives/{id}/updates` | the status-update feed `{health, body, summaryHidden?}`; `health` is `on_track`, `at_risk` or `off_track`. `GET ?include=projects` adds what is below it: `projectUpdates[{projectId, projectName, update}]` for every project under it and `subUpdates[{initiativeId, initiativeName, update}]` for its sub-initiatives |
| `GET /tasks/api/pulse` | [Pulse](/docs/cloud/tasks-pulse.md): the status updates of the projects and initiatives you lead, are a member of, own or follow, newest first: `{updates[{id, kind: project \| initiative, entityId, entityName, health, previousHealth, healthChanged, body, author, createdAt}], overdue[{kind, id, name, health, lastUpdateAt, daysSince, yours}], next}`. `?filter=all\|projects\|initiatives\|changed`, `?limit=` (1 to 100, default 50), `?before=` the last page's `next`. `overdue` (started projects and active initiatives with no update in 7 days) comes on the first page only. `403` for a key that acts for no member |
| `GET /tasks/api/pulse/follows` | `{follows[{kind, id, name, reasons: lead \| owner \| member \| following, following: true \| false \| null, inPulse}]}`: what is in your Pulse and why, and what you unfollowed |
| `GET`, `POST`, `DELETE /tasks/api/projects/{id}/follow`, `/tasks/api/initiatives/{id}/follow` | `{follow}`: read; follow; unfollow (on one you lead, own or are a member of, that mutes it in your Pulse) |
| `GET`, `POST /tasks/api/pulse/digests` | your weekly digests `{digests[{id, weekStart, digest{weekStart, weekEnd, updates, projects, initiatives, changes, latest, overdue, health}, summary, createdAt, readAt, emailedAt, emailNote}], unread}`; `POST` makes last week's now (`201`, or `200` with the one that exists) |
| `GET`, `PATCH /tasks/api/pulse/digests/{id}` | one digest; `PATCH {read: true \| false}` |
| `GET`, `PUT /tasks/api/pulse/settings` | `{settings{summary, dailyCapUsd, spentTodayUsd}}`; `PUT {summary?, dailyCapUsd?}` (0 to 100) needs `org:manage` and is audited (`tasks.pulse.settings_updated`) |
| `GET /tasks/api/dependencies` | the `blocks` relations across all of the org's teams: `{nodes: [{id, identifier, title, teamId, teamKey, stateType, priority}], edges: [{from, to}], truncated}` where `from` blocks `to` (the newest 1500 relations). The page at `/tasks/dependencies` draws it and highlights open chains that end at an Urgent issue |
| `GET /tasks/api/insights` | the Insights panel ([Insights](/docs/cloud/tasks-insights.md)). Takes every `GET /tasks/api/issues` filter parameter (`team`, `assignee`, `label`, `project`, `cycle`, `stateType`, `priority`, `q`, `view`, `filter`, `subteams`, `includeSubIssues`), so it counts what that list shows, plus `measure` (`count`, `effort`, `slaBreach`, `requests` (customer requests), `cycleTime`, `leadTime`, `triageTime`, `age`, `timeInStatus`: per state, how long the issues completed in the window spent there, so `status` is its slice or its segment; `reopened`: moves from a completed or canceled state to any other, counted per move, `n` the issues and `sum` the reopens; `blockedTime`: per issue, the seconds inside the window it was open while one of its `blocked_by` issues was open), `slice` (`time` or a field: `status`, `statusType`, `assignee`, `agent`, `creator`, `label`, `labelGroup` (with `labelGroup=<group id>`), `priority`, `estimate`, `project`, `milestone`, `initiative`, `cycle`, `team`, `parent`, `customer`, `source`, `slaStatus`), `segment` (`none` or a field), `chart` (`bar`, `line`, `scatter`), `date` (`created`, `started`, `completed`, `canceled`, `updated`), `days` (1 to 730, default 90) or `since` and `until` (`YYYY-MM-DD`, UTC, both days included, at most 730 days), `bucket` (`day`, `week`, `month`, `quarter`), `archived=include`, `noPriority=exclude`, `compare=previous` and `format=csv`. Answers `{xs, segs, cells, total, points, unit, since, until, range, bucket, archived, noPriority, labelGroup, prev, tookMs}`, plus `historyFrom` for `reopened` and `blockedTime` (when issues moved in from another tool without that history make it complete only from a later instant inside the window, else null); each group has `n`, `value`, `sum`, and for durations `p25`, `p50`, `p75`, `p90`, `p95` and `mean` (seconds). `format=csv` answers the same numbers as a CSV download. With `drill={"x":…,"seg":…}` it answers the issues behind that group instead (`{issues, total, truncated}`, at most 250). A slow insight stops after 8 s with `400 insight_timeout`. The first version's `by` and `measure=points` still work |
| `GET /tasks/api/insights/flow` | the cumulative flow ([Insights](/docs/cloud/tasks-insights.md#cumulative-flow)): the same filter parameters plus `days` (1 to 730, default 90) or `since` and `until`, `bucket` (default `day` up to 90 days, `week` up to 365, `month` beyond; also `quarter`), `archived=include` and `format=csv`. Answers `{xs, bands, issues, since, until, days, bucket, range, archived, tookMs}`: `xs` the buckets' first days, oldest first (the last holds today, as of now), and one band per state type (`completed`, `canceled`, `started`, `unstarted`, `backlog`, `triage`, bottom to top; a type no issue was in is left out) with the issues in it at the end of each bucket |
| `GET /tasks/api/projects/{id}/insights`, `/tasks/api/cycles/{id}/insights` | a project's or cycle's `burnUp` (scope, started and completed at the end of each UTC day, in issues and points), `scopeChange` (at the start, added, removed, now, per day or week), `velocity` (completed per week for a project, per cycle over the team's last six for a cycle, with the average of the finished ones), `unit` (`points` when the team estimates, else `issues`) and `projection` `{finishOn, rate, remaining, unit}`. A cycle adds `target` (`[{day, value}]` over all its days, flat on weekends) and `onTrack`, then `capacity` `{average, planned, cycles, unit}` while it is upcoming or running, or `success` (percent) once it is over |
| `GET`, `POST /tasks/api/saved-insights` | saved insights ([Dashboards](/docs/cloud/tasks-dashboards.md)): the ones you can see (`?scope=personal\|workspace`), in the Dashboards page's order; save one `{name, query, scope?, scopeLabel?, size?, description?}` where `query` is `GET /tasks/api/insights`'s query string. A shared one about a private team is hidden from those who can't see the team |
| `GET`, `PATCH`, `DELETE /tasks/api/saved-insights/{id}` | read; change (any create field, `position {afterId?, beforeId?}`, `expectVersion`: a stale one is `409 version_conflict`); delete. `{id}` may be the Notes block id `tasks-<id>` |
| `GET /tasks/api/saved-insights/{id}/result` | `{insight, result}`: its numbers now, counted as the caller (`result` as `GET /tasks/api/insights`) |
| `PATCH`, `DELETE /tasks/api/milestones/{id}` | change; delete |
| `GET`, `POST /tasks/api/teams/{id}/cycles` | a team's cycles; add `{startsOn, endsOn, name?}` (an overlap is `409 cycle_overlap`) |
| `POST /tasks/api/teams/{id}/cycles/schedule` | plan the next cycles from the team's cycle settings (`{count?}`) |
| `GET`, `PATCH`, `DELETE /tasks/api/cycles/{id}` | read with its daily history (scope, started, completed); change `{name?, description?, startsOn?, endsOn?}` (a name ending in a number names the later unnamed cycles in sequence; extending into the next upcoming cycle moves its start, `409 would_empty` when it would leave it no days; a completed cycle's dates are `409 cycle_completed`); delete |
| `POST /tasks/api/cycles/{id}/start` | start the next upcoming cycle today: a running cycle completes now (its `endsOn` becomes today) and its open issues move in; answers `{cycle, completed, moved}`. The body is optional: `{today: "YYYY-MM-DD"}`, the caller's own day, taken when it is within a day of the UTC date; without it, today is the day in the member's notification time zone (else their calendar's, else UTC). Another cycle is `409 not_next`, cycles off `409 cycles_off`; one already starting today answers unchanged |
| `GET`, `POST`, `DELETE /tasks/api/teams/{id}/cycles/feed` | your own calendar feed of the team's cycles: `{feed: {url, createdAt} \| null}` (`url` null when it can't be shown again); `POST` makes a new address and stops the old one; `DELETE` turns it off. Agents and API keys get `403` |
| `POST /tasks/api/cycles/{id}/complete` | close it; `{rollover}` (default true) moves its unfinished issues to the next cycle, creating one if needed |

Cycle dates are `YYYY-MM-DD`, and `endsOn` is the first day after the cycle. Progress counts points, with an
unestimated issue as 1 point (0 when its team turns `countUnestimated` off). Canceled and archived issues are left out. The cloud's sweep (every minute) keeps
today's numbers for each running cycle, completes cycles that have ended (rolling their issues over when the team
has `autoRollover`), and keeps `upcoming` cycles planned for teams with cycles on.

### Project updates {#project-updates}

The update schedule, editing, comments and reactions ([Project updates](/docs/cloud/tasks-projects.md)). `{kind}` is `project`
or `initiative`.

| Method and path | What |
|---|---|
| `GET`, `PUT /tasks/api/update-schedules` | `GET` (`?scope=project\|initiative&targetId=`) answers `{workspace{freq, weekday, hour}, teams[{scope, targetId, mode, freq, weekday, hour}], target?{mode, schedule, source}, canManage}`. `PUT {scope: workspace \| team \| project \| initiative, targetId?, mode?: default \| custom \| never \| inherit, freq?: daily \| weekly \| biweekly \| every4w \| monthly, weekday?: 0–6, hour?: 0–23}`: the workspace needs `org:manage`, a team its admins; a project's `inherit` follows its teams, a team's `never` turns it off |
| `PATCH`, `DELETE /tasks/api/project-updates/{id}`, `/tasks/api/initiative-updates/{id}` | `{body?, health?, summaryHidden?}` (a new body or health sets `editedAt`); delete with its comments and reactions. The author or an admin |
| `GET`, `POST /tasks/api/updates/{kind}/{id}/comments` | `{comments[{id, updateKind, updateId, body, author, createdAt, editedAt}]}`, oldest first; add `{body}` |
| `PATCH`, `DELETE /tasks/api/update-comments/{id}` | edit your own `{body}`; delete your own (an admin any) |
| `PUT /tasks/api/updates/{kind}/{id}/reactions` | `{emoji, on?}` → `{reactions}` |

`Project.updateState` (on `GET /tasks/api/projects` and `/projects/{id}`) is `ok`, `due`, `late`, `missing`, `quiet`
or `none`.

### Views, inbox and favourites

| Method and path | What |
|---|---|
| `GET`, `POST /tasks/api/views` | saved views (`?team=`); create `{name, scope, teamId?, filters?, filter?, display?, kind?, tab?, projectFilters?, projectDisplay?}`, where `scope` is `personal`, `workspace` or `team`, `kind` is `issues` (the default) or `projects` (then `projectFilters`, a list of `{field, op, values}` from the projects list's filter, and `projectDisplay`: `layout` `list` or `board`, `groupBy`, `subGroupBy`, `orderBy`, `reverse`, `completed`, `props`), and `tab` shows a team view as a tab. A view carries the caller's `subscription` (`added`, `closed`, `both` or null), `subscribers` and `attention` (why its filter no longer runs, or null). `display` takes `layout`, `group`, `subGroup` (`none` for off), `order`, `reversed`, `completed` (`all`, `day`, `week`, `month`, `none`), `closedByRecency`, `showSubIssues`, `showEmptyGroups`, `nestedSubIssues` (`matching`, `all`, `none`), `hiddenGroups` (up to 200 group keys the view hides) and `properties`; a PATCH keeps the keys it isn't given |
| `GET`, `PATCH`, `DELETE /tasks/api/views/{id}` | read, change, delete (a personal view is its owner's only). A PATCH also takes `tab`, `position` (`{afterId?, beforeId?}`), `ownerId` (a team or workspace view, by its owner or an admin) and a projects view's `projectFilters` and `projectDisplay` |
| `POST /tasks/api/views/{id}/duplicate` | a personal copy you own, `{name?}` ("… (copy)" by default) |
| `POST /tasks/api/views/{id}/subscription` | follow an issues view: `{events}` is `added`, `closed`, `both` or `off`. Notices arrive as `view_match` notifications |
| `GET /tasks/api/notifications` | the caller's inbox (`?filter=all|unread|snoozed|archived`; all hides snoozed ones, `?cursor=`, `?limit=`), with `unread` |
| `PATCH /tasks/api/notifications/{id}` | `{read?, archived?, snoozedUntil?}` |
| `POST /tasks/api/notifications/read-all` | mark everything read; `?archive=1` deletes the read ones, with `&all=1` every one (snoozed too); `?completed=1` deletes the ones about completed or canceled issues (MCP: `tasks_notification_read_all` with `completed: true`) |
| `GET`, `PUT /tasks/api/preferences` | the caller's own Tasks settings (default home, density, first weekday, how an issue opens, inbox switches, the teams folded in the sidebar as `foldedTeams`); see [Settings](/docs/cloud/tasks-settings) |
| `GET`, `POST`, `PATCH`, `DELETE /tasks/api/favorites[/{id}]` | the caller's sidebar favourites (kinds view, issue, project, cycle, team); `PATCH {beforeId}` reorders |

The inbox gets a row when someone assigns you, mentions you, comments on an issue you follow, or changes the state of
an issue you follow. Your own changes never notify you.

### Reminders {#reminders}

| Method and path | What |
|---|---|
| `GET /tasks/api/reminders` | the caller's reminders, soonest first: `?state=pending` (default), `sent` (the last 30 days) or `all`; `?targetKind=issue|project&targetId=` for one issue (id or identifier) or project. Each is `{id, targetKind, targetId, target: {identifier, title, closed}, remindAt, note, onlyIfOpen, memberUid, createdBy, createdAt, sentAt, outcome}` |
| `PUT /tasks/api/reminders` | set one: `{targetKind, targetId, remindAt, note?, onlyIfOpen?, for?}`. `remindAt` is ISO 8601 with its offset, later than now and at most two years ahead; `note` up to 280 characters. It replaces the member's pending reminder on the same target. `for: "assignee"` reminds the issue's assignee instead of the caller (needs write access) |
| `DELETE /tasks/api/reminders/{id}` | cancel a pending reminder or clear a sent one (the caller's, or one the caller set) |

A reminder reaches its member once, within a minute of `remindAt`: an issue's as an inbox item of kind `reminder`
(`detail: {reminderId, note, closed}`, where `closed` is `completed`, `canceled`, `archived` or null), a project's in
the bell. With `onlyIfOpen` a closed target skips it (`outcome: "skipped"`); a deleted target, or one the member can no
longer open, is skipped too. Only targets the caller can see are accepted or listed (private teams as everywhere).
MCP: `tasks_reminder_list`, `tasks_reminder_set`, `tasks_reminder_delete`.

### Releases {#releases}

| Method and path | What |
|---|---|
| `GET /tasks/api/releases` | every live pipeline (with `openCount`, the open issues you can see in its planned and started releases), their planned and started releases and the last five completed of each, and `canManage` |
| `GET /tasks/api/releases/pipelines` | the live pipelines; `?deleted=1` the ones deleted in the last 30 days |
| `POST /tasks/api/releases/pipelines` | make one (owners and admins): `{name, kind?: "scheduled"\|"continuous", teamIds?, rollOpen?, icon?, color?}` |
| `PATCH /tasks/api/releases/pipelines/{id}` | change any of those fields (owners and admins); `{id}` is the id or the name |
| `DELETE /tasks/api/releases/pipelines/{id}` | delete it: its releases leave every issue at once; answers `{ok, restorableUntil}` |
| `POST /tasks/api/releases/pipelines/{id}/restore` | restore a pipeline deleted in the last 30 days (410 `gone` after) |
| `GET /tasks/api/releases/pipelines/{id}/releases` | its releases: started, planned by target date, then finished newest first |
| `POST /tasks/api/releases/pipelines/{id}/releases` | a release: `{name?, description?, targetDate?, status?: "planned"\|"started"}`, named after the last one when no name is given ("2.4" → "2.5"); in a continuous pipeline `{name?, commitSha?, completedAt?}`, made complete |
| `GET /tasks/api/releases/{id}` | the release, its pipeline and the issues in it you can see; `{id}` is the id or the name ("2.5", "Web 2.5") |
| `PATCH /tasks/api/releases/{id}` | `{name?, description?, targetDate?, commitSha?, status?: "planned"\|"started"\|"canceled"}` |
| `POST /tasks/api/releases/{id}/complete` | `{moveOpen?}`: completes it, moves its open issues to the next release (made when none is planned), then runs the teams' release automation; answers `{release, next, moved, automated}` |
| `POST /tasks/api/releases/{id}/issues` | `{issues: ["ENG-12", …]}` (at most 250): adds them; one already in another release of the same pipeline moves to this one |
| `DELETE /tasks/api/releases/{id}/issues?issues=ENG-12,ENG-13` | takes them out |
| `GET`, `PUT /tasks/api/releases/automation/{team}` | the team's release automation: `{stateId, pipelineIds}` (`stateId` null is off, `pipelineIds` null is every pipeline); team admins set it |
| `GET /tasks/api/releases/{id}/draft?from=` | the pipeline's notes template filled for the release (or, with `from`, every completed release from that one on): `{markdown, issues, changes, from}`; saves nothing |
| `GET /tasks/api/releases/pipelines/{id}/changelog?limit=&before=` | completed releases newest first, each `{release, notes, issues, changes, markdown}`, with the whole changelog as `markdown` and `more` |
| `GET`, `POST /tasks/api/releases/pipelines/{id}/keys` | the pipeline's CI keys (owners and admins); `POST {replaces?}` makes one and answers `{key, token}`, the token this once |
| `DELETE /tasks/api/releases/pipelines/{id}/keys/{keyId}` | revoke a key |
| `POST /api/integrations/releases/sync` | for CI, with `Authorization: Bearer vrk_…` instead of a session: see [From any CI](/docs/cloud/tasks-releases.md#from-any-ci) |

A release is `{id, pipelineId, name, description, status, targetDate, commitSha, startedAt, completedAt, createdAt,
issueCount, doneCount, url, hasNotes}`; `GET /releases/{id}` adds `notes`, `notesFrom` and `commits`. A pipeline
also carries its source settings: `source` (`manual`, `github`, `ci`), `repo`, `branch`, `pathGlobs`, `deployEnv`,
`template`, `notesGroup` (`none`, `label`, `team`), `gitSeenAt` and `deploySeenAt`; `PATCH` takes them, and the
release `PATCH` takes `notes` and `notesFrom`. Counts are the issues the caller can see. An issue carries `releaseIds` and
`releasePipelineIds`; the list filters take `release` and `releasePipeline`, and `groupBy=release`. The stream sends
`release` (a pipeline or release changed) and `issue_release` (an issue's releases changed) events. MCP:
`tasks_releasepipeline_*`, `tasks_release_*`, `tasks_releaseautomation_*`, `tasks_releasekey_*` ([Releases](/docs/cloud/tasks-releases.md)).

### Drafts

| Method and path | What |
|---|---|
| `GET /tasks/api/drafts` | the caller's issue drafts, newest first (at most 100): `{drafts: [{id, teamId, title, description, fields, updatedAt}]}` |
| `PUT /tasks/api/drafts/{id}` | create or replace a draft; `id` is a uuid the client picks. Body `{teamId?, title?, description?, fields?}`, where `fields` takes the create request's other keys (`priority`, `assigneeId`, `labelIds`, `dueDate`…) and the composer's `links`, `subIssues` and `recurring` |
| `DELETE /tasks/api/drafts/{id}` | discard it |

A draft belongs to the member who saved it: nobody else can list, change or delete it (another member's id answers
404). Drafts send no notifications and don't appear in the live stream. Text that looks like a secret is refused
(422 `secrets_found`), as on issues. Past 100 drafts, saving one drops the oldest.

### Live changes

`GET /tasks/api/stream` is a server-sent event stream of the org's changes. Each `change` event carries
`{seq, entity, id, op, teamId, issueId, at}`, where `op` is `created`, `updated` or `deleted`. The event `id` is
`seq`, so a reconnect with `Last-Event-ID` (or `?after=`) gets what it missed. When that point is older than the
feed keeps (one day), the stream sends `reset`: load again. The stream sends a ping every 25 seconds and closes
after about 4.5 minutes; reconnect. The events say what changed, not what it became, so read the entity again.

## Errors

Errors are `{error: {message, type, code, param}}`.

| Status | Code | When |
|---|---|---|
| 400 | `invalid_request`, `invalid_filter`, `invalid_cursor`, `invalid_team_key`, `invalid_sort_key`, `parent_cycle`, `relation_self`, `label_group_conflict`, `wrong_team` | the body or query is wrong |
| 401 | `signed_out` | no session |
| 403 | `forbidden`, `no_workspace`, `addon_required` | your role or org can't do this |
| 404 | `not_found` | no such thing in your org |
| 409 | `team_key_taken`, `state_in_use`, `last_state_of_type`, `cycle_overlap`, `cycle_completed`, `relation_exists`, `conflict` | it clashes with what is there |
| 413 | `too_large` | a description over 200 KB or a comment over 64 KB |
| 422 | `secrets_found` | the text holds what looks like a key |

## Related

- [Organisation settings](/docs/cloud/console-settings.md) for buying add-ons
- [Self-hosting Venom Cloud](/docs/cloud/self-hosting.md) for `STRIPE_PRICE_TASKS_SEAT`
