Skip to content

All resources

tasks

17 endpoints

get /bugs/{id}

[Deprecated] Get a task by id via the legacy bug/feature path

Requires authentication

Deprecated alias of GET /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

patch /bugs/{id}

[Deprecated] Update a task via the legacy bug/feature path

Requires authentication

Deprecated alias of PATCH /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Request body: dto.UpdateTaskRequest

NameTypeRequiredDescription
assignedToIdintegernoAssignedToID is the LEGACY single-assignee alias. null unassigns; 0 also unassigns (the shape the pre-set web client sent); a value makes the set exactly that one user. AssigneeIDs wins when both are present. Deprecated: send assigneeIds.
assigneeIdsinteger[]noAssigneeIDs REPLACES the whole assignee set. `[]` and `null` both unassign the task; absent leaves the set untouched. Replace, not add/remove, and deliberately so: - It is what PATCH already means for every other field on this DTO. `{"priority":"high"}` does not merge with the old priority, and a reader has no reason to expect `{"assigneeIds":[7]}` to merge either. - The UI holding the set is a multi-select: it always knows the whole intended set, so add/remove would make it compute a diff the server then has to trust. A replace makes the client's state the request. - It is idempotent, which the PowerSync offline upload queue needs — a replayed queued PATCH must not add the same person twice or, worse, apply a remove that has since been undone. - Add/remove would need its own vocabulary (addAssignees / removeAssignees) with no other caller, and two ways to write one field is exactly how the two drift. The cost is last-write-wins between two people editing assignees at the same moment. That is the same concurrency model every other field here has, and assignment is a low-frequency, human-timescale edit.
clearScheduledAtbooleannoClearScheduledAt, when true, nulls out scheduled_at. Deprecated: send `scheduledAt: null` instead — ScheduledAt is a Nullable now, so an explicit null clears the column on its own. The flag predates that and is part of the published client contract (packages/core UpdateBugRequest / UpdateFeatureRequest), so it is still honoured and still takes precedence over ScheduledAt.
descriptionstringno
dueDatestringnoDueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it.
endDatestringno
estimatedMinutesintegernoEstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear.
parentIdintegernoParentID re-parents the task (feat-181): null (or 0) promotes it back to top-level, a value nests it under that task, absent leaves the link alone. Rejected when it would close a cycle or push the tree past repository.MaxTaskDepth. Nullable rather than *uint for the reason the type exists: "no parent" is a state the client has to be able to REQUEST, and a *uint cannot tell an explicit null from an absent key — un-nesting a task would be indistinguishable from not mentioning it. 0 is accepted as a second spelling of the clear because that is what the MCP tool already takes.
prioritydomain.Priorityno
pullRequestUrlstringnoM6: manually-linked PR URL. null or "" clears the link.
scheduledAtstringnoScheduledAt sets the single planned day the .ics calendar feed plots the task on (see domain.Bug.ScheduledAt). null or "" clears it. Accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate).
severitystring (critical | high | medium | low | info)noSeverity (impact) — null or "" clears the grade.
sprintstringnoSprint: null or "" clears the bucket; a non-empty value sets it.
startDatestringnoThe Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD".
statusstringnoSee CreateTaskRequest.Status — a column key, not the closed enum.
storyPointsintegernoM4 power-feature fields. null clears the estimate / the logged time.
targetBranchstringnoTargetBranch: null or "" falls the task back to the project default.
timeSpentMinutesintegerno
titlestringno

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

delete /bugs/{id}

[Deprecated] Delete a task via the legacy bug/feature path

Requires authentication

Deprecated alias of DELETE /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

get /features/{id}

[Deprecated] Get a task by id via the legacy bug/feature path

Requires authentication

Deprecated alias of GET /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

patch /features/{id}

[Deprecated] Update a task via the legacy bug/feature path

Requires authentication

Deprecated alias of PATCH /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Request body: dto.UpdateTaskRequest

NameTypeRequiredDescription
assignedToIdintegernoAssignedToID is the LEGACY single-assignee alias. null unassigns; 0 also unassigns (the shape the pre-set web client sent); a value makes the set exactly that one user. AssigneeIDs wins when both are present. Deprecated: send assigneeIds.
assigneeIdsinteger[]noAssigneeIDs REPLACES the whole assignee set. `[]` and `null` both unassign the task; absent leaves the set untouched. Replace, not add/remove, and deliberately so: - It is what PATCH already means for every other field on this DTO. `{"priority":"high"}` does not merge with the old priority, and a reader has no reason to expect `{"assigneeIds":[7]}` to merge either. - The UI holding the set is a multi-select: it always knows the whole intended set, so add/remove would make it compute a diff the server then has to trust. A replace makes the client's state the request. - It is idempotent, which the PowerSync offline upload queue needs — a replayed queued PATCH must not add the same person twice or, worse, apply a remove that has since been undone. - Add/remove would need its own vocabulary (addAssignees / removeAssignees) with no other caller, and two ways to write one field is exactly how the two drift. The cost is last-write-wins between two people editing assignees at the same moment. That is the same concurrency model every other field here has, and assignment is a low-frequency, human-timescale edit.
clearScheduledAtbooleannoClearScheduledAt, when true, nulls out scheduled_at. Deprecated: send `scheduledAt: null` instead — ScheduledAt is a Nullable now, so an explicit null clears the column on its own. The flag predates that and is part of the published client contract (packages/core UpdateBugRequest / UpdateFeatureRequest), so it is still honoured and still takes precedence over ScheduledAt.
descriptionstringno
dueDatestringnoDueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it.
endDatestringno
estimatedMinutesintegernoEstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear.
parentIdintegernoParentID re-parents the task (feat-181): null (or 0) promotes it back to top-level, a value nests it under that task, absent leaves the link alone. Rejected when it would close a cycle or push the tree past repository.MaxTaskDepth. Nullable rather than *uint for the reason the type exists: "no parent" is a state the client has to be able to REQUEST, and a *uint cannot tell an explicit null from an absent key — un-nesting a task would be indistinguishable from not mentioning it. 0 is accepted as a second spelling of the clear because that is what the MCP tool already takes.
prioritydomain.Priorityno
pullRequestUrlstringnoM6: manually-linked PR URL. null or "" clears the link.
scheduledAtstringnoScheduledAt sets the single planned day the .ics calendar feed plots the task on (see domain.Bug.ScheduledAt). null or "" clears it. Accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate).
severitystring (critical | high | medium | low | info)noSeverity (impact) — null or "" clears the grade.
sprintstringnoSprint: null or "" clears the bucket; a non-empty value sets it.
startDatestringnoThe Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD".
statusstringnoSee CreateTaskRequest.Status — a column key, not the closed enum.
storyPointsintegernoM4 power-feature fields. null clears the estimate / the logged time.
targetBranchstringnoTargetBranch: null or "" falls the task back to the project default.
timeSpentMinutesintegerno
titlestringno

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

delete /features/{id}

[Deprecated] Delete a task via the legacy bug/feature path

Requires authentication

Deprecated alias of DELETE /tasks/{id}. Use /api/v1/tasks/{id}.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope

get /projects/{id}/board

Get a project's board (project + active task cards)

Requires authentication

One round-trip board payload: the project plus lean active (non-done) task items for bug/feature/change, capped for scale.

Parameters

NameInTypeRequiredDescription
idpathintegeryesProject id

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

get /projects/{projectId}/tasks

List tasks in a project

Requires authentication

Returns all tasks for a project. Optional query filters narrow by type/status/priority/assignee/search.

Parameters

NameInTypeRequiredDescription
projectIdpathintegeryesProject id
typequerystring (bug | feature | change)noFilter by task type
statusquerystringnoFilter by status
priorityquerystringnoFilter by priority
assignedToqueryintegernoFilter by assignee user id — matches tasks this user is AMONG the assignees of
searchquerystringnoFull-text search on title/description
limitqueryintegernoPage size (default 500, max 500)
cursorquerystringnoOpaque keyset cursor from a previous page's meta.nextCursor
withTotalquerybooleannoInclude the total match count in meta (admin/analytics; off the hot path)

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /projects/{projectId}/tasks/{type}/{taskNumber}

Get a task by its per-project number

Requires authentication

Resolves the human-facing (project, type, taskNumber) address (e.g. bug-3), following legacy number aliases.

Parameters

NameInTypeRequiredDescription
projectIdpathintegeryesProject id
typepathstring (bug | feature | change | test)yesTask type
taskNumberpathintegeryesPer-project task number

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

get /projects/{projectId}/tasks/by-number/{taskNumber}

Resolve a task by its per-project number (type-agnostic)

Requires authentication

Resolves the unified per-project task number without a type discriminator, so the /tasks/:taskNumber route resolves in one request. Follows legacy per-type number aliases as a fallback for old deep links.

Parameters

NameInTypeRequiredDescription
projectIdpathintegeryesProject id
taskNumberpathintegeryesPer-project task number

Responses

  • 200 OK · apimodel.TaskDetail
  • 404 Not Found · apimodel.ErrorEnvelope

post /tasks

Create a task

Requires authentication

Creates a bug/feature/change. Required: projectId, type, title. Returns the new task.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional key making the create safe to retry

Request body: dto.CreateTaskRequest

NameTypeRequiredDescription
assignedToIdintegernoAssignedToID is the LEGACY single-assignee alias, kept because published clients and API-token consumers send it. It means "the set is exactly this one user". AssigneeIDs wins when both are present — see ResolvedAssigneeIDs. Removed by the contract migration's code half. Deprecated: send assigneeIds.
assigneeIdsinteger[]noAssigneeIDs is the task's assignee SET. Empty or absent creates the task unassigned. Duplicates and zeros are ignored (see ResolvedAssigneeIDs).
descriptionstringno
dueDateobjectnoDueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate).
estimatedMinutesintegernoEstimatedMinutes is the expected effort in REAL minutes (see domain.Bug.EstimatedMinutes). Absent means no estimate; the column stays NULL and the UI renders the task as unestimated.
parentIdintegernoParentID — when set, the new task becomes a sub-issue of the referenced task. Optional; absent means top-level.
prioritydomain.Priorityno
projectIdintegerno
severityobjectnoSeverity (impact) is orthogonal to Priority (scheduling). Optional.
sprintstringno
statusstringnoA project COLUMN KEY, not a member of the domain.Status const set — the write side of the same truth the read models carry. Verified: PATCH with "needs_qa" (a real column on project 44) returns 200 and reads back, because Go does not check const-set membership when unmarshalling into a named string type. So the closed enum was the SPEC's invention, and it made the generated clients unable to express a move to any column outside the canonical four — iOS had to hand-build that one request. Note this DTO deliberately has no `oneof` validation, unlike the bug/feature DTOs whose enum really is closed.
storyPointsintegernoM4 power-feature fields (gated in the UI by project toggles).
targetBranchstringnoTargetBranch is meaningful only when Type==bug; ignored otherwise. Kept on the request shape so the frontend doesn't need a different DTO per type.
timeSpentMinutesintegerno
titlestringno
typedomain.TaskTypeno
widgetHtmlstringnoWidgetHTML carries a self-contained HTML artifact when creating a task from a brainstorming-canvas widget card (promote flow).

Responses

  • 201 Created · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /tasks/{id}

Get a task by id

Requires authentication

Returns the task with rollup counters, denormalized emails, and (when wired) subscription state.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

patch /tasks/{id}

Update a task

Requires authentication

Partial update — every field is optional, nil means "leave unchanged". Returns the updated task.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Request body: dto.UpdateTaskRequest

NameTypeRequiredDescription
assignedToIdintegernoAssignedToID is the LEGACY single-assignee alias. null unassigns; 0 also unassigns (the shape the pre-set web client sent); a value makes the set exactly that one user. AssigneeIDs wins when both are present. Deprecated: send assigneeIds.
assigneeIdsinteger[]noAssigneeIDs REPLACES the whole assignee set. `[]` and `null` both unassign the task; absent leaves the set untouched. Replace, not add/remove, and deliberately so: - It is what PATCH already means for every other field on this DTO. `{"priority":"high"}` does not merge with the old priority, and a reader has no reason to expect `{"assigneeIds":[7]}` to merge either. - The UI holding the set is a multi-select: it always knows the whole intended set, so add/remove would make it compute a diff the server then has to trust. A replace makes the client's state the request. - It is idempotent, which the PowerSync offline upload queue needs — a replayed queued PATCH must not add the same person twice or, worse, apply a remove that has since been undone. - Add/remove would need its own vocabulary (addAssignees / removeAssignees) with no other caller, and two ways to write one field is exactly how the two drift. The cost is last-write-wins between two people editing assignees at the same moment. That is the same concurrency model every other field here has, and assignment is a low-frequency, human-timescale edit.
clearScheduledAtbooleannoClearScheduledAt, when true, nulls out scheduled_at. Deprecated: send `scheduledAt: null` instead — ScheduledAt is a Nullable now, so an explicit null clears the column on its own. The flag predates that and is part of the published client contract (packages/core UpdateBugRequest / UpdateFeatureRequest), so it is still honoured and still takes precedence over ScheduledAt.
descriptionstringno
dueDatestringnoDueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it.
endDatestringno
estimatedMinutesintegernoEstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear.
parentIdintegernoParentID re-parents the task (feat-181): null (or 0) promotes it back to top-level, a value nests it under that task, absent leaves the link alone. Rejected when it would close a cycle or push the tree past repository.MaxTaskDepth. Nullable rather than *uint for the reason the type exists: "no parent" is a state the client has to be able to REQUEST, and a *uint cannot tell an explicit null from an absent key — un-nesting a task would be indistinguishable from not mentioning it. 0 is accepted as a second spelling of the clear because that is what the MCP tool already takes.
prioritydomain.Priorityno
pullRequestUrlstringnoM6: manually-linked PR URL. null or "" clears the link.
scheduledAtstringnoScheduledAt sets the single planned day the .ics calendar feed plots the task on (see domain.Bug.ScheduledAt). null or "" clears it. Accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate).
severitystring (critical | high | medium | low | info)noSeverity (impact) — null or "" clears the grade.
sprintstringnoSprint: null or "" clears the bucket; a non-empty value sets it.
startDatestringnoThe Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD".
statusstringnoSee CreateTaskRequest.Status — a column key, not the closed enum.
storyPointsintegernoM4 power-feature fields. null clears the estimate / the logged time.
targetBranchstringnoTargetBranch: null or "" falls the task back to the project default.
timeSpentMinutesintegerno
titlestringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

delete /tasks/{id}

Delete a task

Requires authentication

Permanently deletes a task; junction rows (initiatives, links) cascade.

Parameters

NameInTypeRequiredDescription
idpathintegeryesTask id

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 404 Not Found · apimodel.ErrorEnvelope

post /tasks/bulk

Bulk-update tasks

Requires authentication

Applies a partial field set to many tasks at once; every id must belong to the caller's org, and the caller must be able to edit each task's project and any destination projectId (403 on any miss, nothing written).

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 403 Forbidden · apimodel.ErrorEnvelope

post /tasks/check-duplicates

Find likely-duplicate tasks

Requires authentication

Returns existing same-type tasks whose title matches the given one, so the create form can warn before filing.

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /tasks/my-work

List my work across all projects

Requires authentication

Cursor-paginated, org-wide list of the caller's tasks for one involvement segment (assigned / created / following). Scoped to projects the caller can reach; excludes finished work unless includeDone=1.

Parameters

NameInTypeRequiredDescription
involvementquerystring (assigned | created | following)noWhich segment to list (default assigned)
includeDonequerybooleannoInclude tasks in a finished column (default false)
limitqueryintegernoPage size (default 50, max 200)
cursorquerystringnoOpaque keyset cursor from a previous page's meta.nextCursor

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope