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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task id |
Request body: dto.UpdateTaskRequest
| Name | Type | Required | Description |
|---|---|---|---|
| assignedToId | integer | no | AssignedToID 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. |
| assigneeIds | integer[] | no | AssigneeIDs 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. |
| clearScheduledAt | boolean | no | ClearScheduledAt, 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. |
| description | string | no | |
| dueDate | string | no | DueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it. |
| endDate | string | no | |
| estimatedMinutes | integer | no | EstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear. |
| parentId | integer | no | ParentID 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. |
| priority | domain.Priority | no | |
| pullRequestUrl | string | no | M6: manually-linked PR URL. null or "" clears the link. |
| scheduledAt | string | no | ScheduledAt 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). |
| severity | string (critical | high | medium | low | info) | no | Severity (impact) — null or "" clears the grade. |
| sprint | string | no | Sprint: null or "" clears the bucket; a non-empty value sets it. |
| startDate | string | no | The Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD". |
| status | string | no | See CreateTaskRequest.Status — a column key, not the closed enum. |
| storyPoints | integer | no | M4 power-feature fields. null clears the estimate / the logged time. |
| targetBranch | string | no | TargetBranch: null or "" falls the task back to the project default. |
| timeSpentMinutes | integer | no | |
| title | string | no |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task id |
Request body: dto.UpdateTaskRequest
| Name | Type | Required | Description |
|---|---|---|---|
| assignedToId | integer | no | AssignedToID 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. |
| assigneeIds | integer[] | no | AssigneeIDs 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. |
| clearScheduledAt | boolean | no | ClearScheduledAt, 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. |
| description | string | no | |
| dueDate | string | no | DueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it. |
| endDate | string | no | |
| estimatedMinutes | integer | no | EstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear. |
| parentId | integer | no | ParentID 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. |
| priority | domain.Priority | no | |
| pullRequestUrl | string | no | M6: manually-linked PR URL. null or "" clears the link. |
| scheduledAt | string | no | ScheduledAt 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). |
| severity | string (critical | high | medium | low | info) | no | Severity (impact) — null or "" clears the grade. |
| sprint | string | no | Sprint: null or "" clears the bucket; a non-empty value sets it. |
| startDate | string | no | The Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD". |
| status | string | no | See CreateTaskRequest.Status — a column key, not the closed enum. |
| storyPoints | integer | no | M4 power-feature fields. null clears the estimate / the logged time. |
| targetBranch | string | no | TargetBranch: null or "" falls the task back to the project default. |
| timeSpentMinutes | integer | no | |
| title | string | no |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Project 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| projectId | path | integer | yes | Project id |
| type | query | string (bug | feature | change) | no | Filter by task type |
| status | query | string | no | Filter by status |
| priority | query | string | no | Filter by priority |
| assignedTo | query | integer | no | Filter by assignee user id — matches tasks this user is AMONG the assignees of |
| search | query | string | no | Full-text search on title/description |
| limit | query | integer | no | Page size (default 500, max 500) |
| cursor | query | string | no | Opaque keyset cursor from a previous page's meta.nextCursor |
| withTotal | query | boolean | no | Include 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| projectId | path | integer | yes | Project id |
| type | path | string (bug | feature | change | test) | yes | Task type |
| taskNumber | path | integer | yes | Per-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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| projectId | path | integer | yes | Project id |
| taskNumber | path | integer | yes | Per-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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | string | no | Optional key making the create safe to retry |
Request body: dto.CreateTaskRequest
| Name | Type | Required | Description |
|---|---|---|---|
| assignedToId | integer | no | AssignedToID 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. |
| assigneeIds | integer[] | no | AssigneeIDs is the task's assignee SET. Empty or absent creates the task unassigned. Duplicates and zeros are ignored (see ResolvedAssigneeIDs). |
| description | string | no | |
| dueDate | object | no | DueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). |
| estimatedMinutes | integer | no | EstimatedMinutes 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. |
| parentId | integer | no | ParentID — when set, the new task becomes a sub-issue of the referenced task. Optional; absent means top-level. |
| priority | domain.Priority | no | |
| projectId | integer | no | |
| severity | object | no | Severity (impact) is orthogonal to Priority (scheduling). Optional. |
| sprint | string | no | |
| status | string | no | A 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. |
| storyPoints | integer | no | M4 power-feature fields (gated in the UI by project toggles). |
| targetBranch | string | no | TargetBranch is meaningful only when Type==bug; ignored otherwise. Kept on the request shape so the frontend doesn't need a different DTO per type. |
| timeSpentMinutes | integer | no | |
| title | string | no | |
| type | domain.TaskType | no | |
| widgetHtml | string | no | WidgetHTML 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task id |
Request body: dto.UpdateTaskRequest
| Name | Type | Required | Description |
|---|---|---|---|
| assignedToId | integer | no | AssignedToID 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. |
| assigneeIds | integer[] | no | AssigneeIDs 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. |
| clearScheduledAt | boolean | no | ClearScheduledAt, 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. |
| description | string | no | |
| dueDate | string | no | DueDate accepts both RFC3339 and bare "YYYY-MM-DD" (see FlexDate). null or "" clears it. |
| endDate | string | no | |
| estimatedMinutes | integer | no | EstimatedMinutes: null clears the estimate, returning the task to unestimated. 0 is a value, not a clear. |
| parentId | integer | no | ParentID 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. |
| priority | domain.Priority | no | |
| pullRequestUrl | string | no | M6: manually-linked PR URL. null or "" clears the link. |
| scheduledAt | string | no | ScheduledAt 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). |
| severity | string (critical | high | medium | low | info) | no | Severity (impact) — null or "" clears the grade. |
| sprint | string | no | Sprint: null or "" clears the bucket; a non-empty value sets it. |
| startDate | string | no | The Calendar view's planned span. null or "" clears; a value sets. FlexDate accepts RFC3339 or bare "YYYY-MM-DD". |
| status | string | no | See CreateTaskRequest.Status — a column key, not the closed enum. |
| storyPoints | integer | no | M4 power-feature fields. null clears the estimate / the logged time. |
| targetBranch | string | no | TargetBranch: null or "" falls the task back to the project default. |
| timeSpentMinutes | integer | no | |
| title | string | no |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Task 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| involvement | query | string (assigned | created | following) | no | Which segment to list (default assigned) |
| includeDone | query | boolean | no | Include tasks in a finished column (default false) |
| limit | query | integer | no | Page size (default 50, max 200) |
| cursor | query | string | no | Opaque keyset cursor from a previous page's meta.nextCursor |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope