Skip to content
Docs menu

Venom Tasks API

Read and change your org's Venom Tasks issues, teams, workflows, projects, cycles, views and inbox over the console session, and follow changes live.

View .md

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

# 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), 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)
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)
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)
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)
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)
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).

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:

    > [!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, 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 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.

{ "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)
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: {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: 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). 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): 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): 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

The update schedule, editing, comments and reactions (Project updates). {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
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
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

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
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

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

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).

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