Tasks
Project Tasks.
Capture or explicitly refresh a checked Task result set
/api/v1/workspaces/{workspace_id}/task-result-setsMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
application/jsonobjectChecked canonical query; Core normalizes filters and intersects authorized Project scope. State and resolution follow the Workspace Task list contract. Optional filter_terms/order apply within the ten-page/1000-row checked scan ceiling; they do not introduce unbounded search. Saved views retain these fields and reopening creates a fresh result set with current coverage.
Responses
objectChecked canonical query; Core normalizes filters and intersects authorized Project scope. State and resolution follow the Workspace Task list contract. Optional filter_terms/order apply within the ten-page/1000-row checked scan ceiling; they do not introduce unbounded search. Saved views retain these fields and reopening creates a fresh result set with current coverage.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read an exact Task result-set version
/api/v1/workspaces/{workspace_id}/task-result-sets/{id}Membership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
objectChecked canonical query; Core normalizes filters and intersects authorized Project scope. State and resolution follow the Workspace Task list contract. Optional filter_terms/order apply within the ten-page/1000-row checked scan ceiling; they do not introduce unbounded search. Saved views retain these fields and reopening creates a fresh result set with current coverage.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Select exact result-set Task identities
/api/v1/workspaces/{workspace_id}/task-selectionsMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read a frozen Task selection
/api/v1/workspaces/{workspace_id}/task-selections/{id}Membership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Hydrate up to 100 exact result-set targets with current compact Task previews
/api/v1/workspaces/{workspace_id}/task-result-sets/{id}/hydrateMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Reauthorize up to100 selected Task identities
/api/v1/workspaces/{workspace_id}/task-selections/{id}/hydrateMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List personal Task queries
/api/v1/workspaces/{workspace_id}/task-saved-viewsMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Create or revision-check a personal Task query
/api/v1/workspaces/{workspace_id}/task-saved-viewsMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
application/jsonobjectChecked canonical query; Core normalizes filters and intersects authorized Project scope. State and resolution follow the Workspace Task list contract. Optional filter_terms/order apply within the ten-page/1000-row checked scan ceiling; they do not introduce unbounded search. Saved views retain these fields and reopening creates a fresh result set with current coverage.
objectMembership-private Project Task presentation. Maximum serialized size is 16 KiB. Query Project scope must match project_id. Missing parameters use the current Project Task presentation defaults; unsupported keys or values are rejected. An update omitting definition preserves the existing definition, and an existing definition cannot move to another Project.
Responses
objectChecked canonical query; Core normalizes filters and intersects authorized Project scope. State and resolution follow the Workspace Task list contract. Optional filter_terms/order apply within the ten-page/1000-row checked scan ceiling; they do not introduce unbounded search. Saved views retain these fields and reopening creates a fresh result set with current coverage.
objectMembership-private Project Task presentation. Maximum serialized size is 16 KiB. Query Project scope must match project_id. Missing parameters use the current Project Task presentation defaults; unsupported keys or values are rejected. An update omitting definition preserves the existing definition, and an existing definition cannot move to another Project.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Delete an exact personal Task-query revision
/api/v1/workspaces/{workspace_id}/task-saved-views/deleteMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Create or edit a versioned Document draft
/api/v1/workspaces/{workspace_id}/document-patchesMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read an exact Document draft version
/api/v1/workspaces/{workspace_id}/document-patches/{id}Membership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Propose bounded versioned changes
/api/v1/workspaces/{workspace_id}/change-setsMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read an exact proposal and accessible outcomes
/api/v1/workspaces/{workspace_id}/change-sets/{id}Membership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Apply an exact reviewed proposal
/api/v1/workspaces/{workspace_id}/change-sets/applyMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Approve or reject an exact proposal as its initiating human
/api/v1/workspaces/{workspace_id}/change-sets/{id}/reviewMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Only the initiating human can review this exact digest; approval cannot be supplied through MCP.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Resolve a committed operation under current authority
/api/v1/workspaces/{workspace_id}/operation-receipts/{id}Membership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Conditionally compensate an initiating member operation
/api/v1/workspaces/{workspace_id}/operation-receipts/undoMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Requires a browser session and CSRF. Reuse Idempotency-Key only for the same request. Before retrying an uncertain write, resolve its operation receipt.
Path Parameters
Header Parameters
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Resolve an exact member identity with ambiguity preserved
/api/v1/workspaces/{workspace_id}/members/resolveMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Query Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read bounded canonical Task context
/api/v1/workspaces/{workspace_id}/tasks/{id}/contextMembership-private native work capability. Current Workspace and resource permissions are checked on every request. Responses use Cache-Control: no-store. Exact versions never refresh or replace selected targets implicitly.
Path Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List access-filtered Task activity
/api/v1/tasks/{task_id}/activityReturns the Task's own history plus associated comment and Task relation events, newest first. It shares the Workspace Activity retention, redaction, current-access filtering, grouping, and safe projection rules, and it additionally includes ordinary property changes (such as a title correction) that the Workspace feed omits. Personal following and muting changes and ordinary reactions are not included. Private-Project access is re-evaluated for every request.
Path Parameters
Query Parameters
Responses
integer <int64>·min 0Authorized collection size before cursor bounds; refreshed at read time. Activity counts admitted events before display grouping and Comments include retained ordinals.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read bounded Workspace Knowledge context related to a Task
/api/v1/workspaces/{workspace_id}/tasks/{task_id}/related-contextReturns a permission-filtered, read-only projection. Globally unconfigured, disabled, unentitled, unacknowledged, empty-scope, and out-of-scope Knowledge conditions use the empty state; unavailable is reserved for genuine retrieval/currentness failures after eligibility. Neither state blocks the owning Task workflow. Indexed subjects may discover Documents through shared distinctive title terms without a cross-domain link generation. Inferred suggestions explain their shared terms and never create or change canonical Task relations.
Path Parameters
Query Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·max 4096Signed Workspace/User/session-bound replay custody; present only after a successful requested canonical baseline.
stringDecimal-string snapshot position; present only with a successful baseline cursor.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Confirm or discard one Suggestions-tab finding
/api/v1/workspaces/{workspace_id}/tasks/{task_id}/suggestion-feedbackConfirming a Task finding creates a canonical relates relation; confirming a Document links it. Confirming a commit finding adds the verified commit to Linked development after rechecking the current Task, comment and repository binding. Commit outcomes persist in Core; Task and Document outcomes also relay to Workspace Knowledge. Confirming is idempotent and discarding suppresses the finding for this Task.
Path Parameters
Header Parameters
Request Body
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List bounded Workspace Tasks
/api/v1/workspaces/{workspace_id}/tasksReturns a newest-updated-first cursor page of Tasks in the current
Workspace. It is an activity collection, not a text-search endpoint.
Repeated project_id and status_category filters use OR semantics;
a Project outside the Workspace simply contributes no rows.
With consistency=checked, Core binds continuation to the normalized filters,
caller, collection version and visibility revision. Complete coverage requires
an unchanged scan ending without a cursor. Changed data or permissions returns
an empty stale page without continuation. Ten pages or 1,000 rows caps a scan;
an incomplete capped result remains partial. Restart stale scans explicitly.
Omitted consistency preserves legacy pagination without a completeness claim.
Path Parameters
Query Parameters
string[]·max 5Restrict to one or more Status lifecycle categories.
backlogtodoin_progressin_reviewdonestring[]·max 8Keep Tasks whose current stage has every named lifecycle behavior
enabled (AND semantics, at most 8 distinct keys). Keys are the
Task-applicable entries of listLifecycleBehaviors; an unknown or
non-Task key is a 400. Totals and cursors honor the filter.
notifyshow_activetreat_as_closedcounts_as_completedallow_changesstring <date-time>Include Tasks updated at or after this instant.
boolean·default falseInclude archived Tasks; omitted or false returns active Tasks only.
string·default allActive means unresolved; omitted or all includes active and resolved Tasks.
activeresolvedallResponses
stringComplete proves this filtered authorized scan at its observation boundary; partial and stale cannot prove absence.
completepartialstaleinteger·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Resolve a Task's canonical Workspace URL
/api/v1/workspaces/{workspace_id}/tasks/{task_code}Resolves the stable, case-insensitive Task code inside the current Workspace after Workspace and Project read authorization. Unlike active Task collections, this route returns archived and trashed Tasks during recovery and the safe Task tombstone after purge so canonical browser URLs remain durable without exposing content removed by retention. Native bearer reads use live Workspace membership and the same resource visibility. Invalid native credentials never fall back to browser cookies.
Path Parameters
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Update up to 100 explicitly selected Tasks
/api/v1/workspaces/{workspace_id}/tasks/bulkApplies the same patch independently to one through 100 explicit Task IDs in the current Workspace. Every item carries the revision it was selected from; authorization and compare-and-swap checks happen per Task, so selection never grants access. The response always contains one outcome per requested item in request order. Retry only failed items with their then-current revisions and a fresh idempotency key.
This initial synchronous command supports status, assignee, priority, due date, and milestone changes. It has no snapshot-query input, asynchronous job, progress, or cancellation contract; requests over 100 items are rejected. Archive/restore and labels remain separate operations with their own accepted lifecycle rules.
Path Parameters
Header Parameters
Request Body
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read the caller's bounded My Work view
/api/v1/workspaces/{workspace_id}/workReturns one caller-scoped Task view. The server obtains the actor from
the authenticated principal; no actor filter is accepted. Browser
sessions and bearer credentials resolve the same live caller
authorization; bearer credentials never inherit browser cookies.
Date membership uses the actor's persisted IANA timezone and the
returned as_of_date.
Path Parameters
Query Parameters
Responses
integer <int64>·min 0Authorized collection size before cursor bounds; refreshed at read time. Activity counts admitted events before display grouping and Comments include retained ordinals.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Read the caller's actively followed Tasks
/api/v1/workspaces/{workspace_id}/subscribed-tasksReturns Tasks the caller currently follows (subscription state
following) in the Workspace, newest subscription activity first.
The server obtains the actor from the authenticated principal; no
actor filter is accepted. Muted and unfollowed subscriptions are
excluded, as are Tasks in a private Project the caller cannot see.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List Project Tasks
/api/v1/projects/{project_id}/tasksReturns one page ordered by the Task's immutable project-local number by default. Column orders require exactly one status_id, exclude archived Tasks, and return a snapshot-consistent column total and advisory movement permission instead of global history counts. Cursors bind the Project, Status, order and filters. Rank pagination is a live traversal; concurrent moves can require refreshing earlier pages.
Path Parameters
Query Parameters
string·default allFilter by the lifecycle umbrella derived from current resolution facts.
activeresolvedallstring·default numberColumn rank order or newest resolution first; number retains history semantics.
numberrankrank_descresolved_descstring <date-time>Inclusive recent-resolution cutoff for column orders; does not restrict column.total.
string <uuid>Start strictly after this current Task in the chosen rank direction. Must belong to this Project and Status. Cannot accompany cursor or resolved_desc. Other history filters are not accepted with column orders.
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Create a Task
/api/v1/projects/{project_id}/tasksCanonical content with an unsupported schema or an attempted schema 2-to-1 downgrade returns 409 document_schema_version_unsupported. Restoring an older Document revision retains an existing schema 2 floor. Creates a Task with an atomically allocated project-local number. Accepts scoped bearer credentials with live Workspace and Project authorization. Browser sessions still require CSRF; bearer callers omit it.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>Omit to use the Workspace's default Task workflow category.
string <uuid>Omit to use the Workspace's default Task assignee policy.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Change a Task relation type
/api/v1/task-relations/{relation_id}Changes only the relation type. The related Tasks cannot be edited or replaced by this operation.
Path Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Header Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Update a Task
/api/v1/tasks/{task_id}Canonical content with an unsupported schema or an attempted
schema 2-to-1 downgrade returns 409 document_schema_version_unsupported.
Restoring an older Document revision retains an existing schema 2 floor.
Browser callers require the session-bound CSRF header. Bearer callers
omit cookies and CSRF; all callers retain identical authorization,
idempotency and revision preconditions.
Applies an optimistic compare-and-swap on the accepted core Task
fields. Every field is optional; an omitted field keeps its current
value, and an explicit assignee_actor_id: null clears the
assignee. If-Match must carry the revision last observed by the
client. A Task with any relation, including a parent/subtask relation,
must be unlinked before its project_id can change; the API returns
422 task_has_relations rather than creating a cross-Project edge.
Path Parameters
Header Parameters
string·min 1·max 200Required when this operation uses browserSession; native bearer callers omit it because no ambient cookie is sent.
string·min 16·max 200Opaque client-generated key for safely retrying this operation.
Request Body
application/jsonstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>An explicit null clears the assignee.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Archive a Task
/api/v1/tasks/{task_id}Archives a Task with optimistic concurrency. The current Task revision
must be supplied in If-Match; retries with the same idempotency key
replay the original response.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List Task description revisions
/api/v1/tasks/{task_id}/description-revisionsReturns immutable Task-description snapshots newest first. The history begins with the baseline captured when revision retention was enabled; older content is never reconstructed or implied.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Restore a Task description revision
/api/v1/tasks/{task_id}/description-revisions/{revision}/restoreCopies one retained description snapshot into a new Task revision.
The source snapshot remains immutable, and If-Match prevents a
restore from overwriting a newer Task change.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Move a Task to trash
/api/v1/tasks/{task_id}/trashRemoves the Task from active collections, search, notification delivery, reminders, recurrence, and integration writes. Content and associations remain recoverable until the fixed 30-day retention clock expires. Repeating the desired-state command at the same revision is unchanged.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Restore an archived or trashed Task
/api/v1/tasks/{task_id}/restoreRestores a reversible Task to active state after revalidating its current Project, Status, assignee, caller access, and revision. A conflict must be remediated before retry. A purged tombstone cannot be restored.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Duplicate a Task
/api/v1/tasks/{task_id}/duplicateCreates a new independent Task from an active source Task. Title, description, and priority are always copied. Callers explicitly choose whether to copy the current assignee, due date, milestone, labels, attachment links, and the active subtask tree. Comments, Activity, notification history, assignment periods, time entries, subscriptions, and integration execution history are never copied.
Cross-Project duplication maps Statuses by semantic category unless an
explicit destination Status is supplied, keeps Workspace labels, maps
Project labels by normalized name, and reports optional resources that
cannot be copied in issues. Milestones remain Project-local. The
command copies at most 25 active descendants and 100 clean attachment
links per copied Task; it never duplicates stored attachment objects or
storage quota. If-Match protects the source revision, and retries with
the same idempotency key replay the original result.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Request Body
application/jsonstring <uuid>Destination Project. Omit or use null to duplicate inside the source Project.
string <uuid>Explicit destination Status for the new root. Omit or use null to preserve the Status in the same Project or map its category across Projects.
booleanCopy at most 25 active descendants while preserving the parent hierarchy.
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List a Task's assignment history
/api/v1/tasks/{task_id}/assignmentsReturns immutable primary-assignee periods newest first. Imported periods can have an unknown assignment instant.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List factual Task participants
/api/v1/tasks/{task_id}/participantsReturns the Task creator, current primary assignee, and previous primary assignees without implying subscription or notification state.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Get the current user's Task subscription
/api/v1/tasks/{task_id}/subscriptionReturns the caller's revisioned relationship, or a null subscription when no automatic or manual decision exists. Reading or mutating this relationship never grants Task access.
Path Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Follow a Task
/api/v1/tasks/{task_id}/subscriptionIdempotently sets the caller's manual subscription state to following. A manual state is authoritative over later automatic creator, assignee, commenter, or mention triggers.
Path Parameters
Header Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Unfollow a Task
/api/v1/tasks/{task_id}/subscriptionIdempotently records an explicit unfollowed state. The row and prior notification history remain retained.
Path Parameters
Header Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Mute a Task
/api/v1/tasks/{task_id}/subscription/muteIdempotently suppresses Task subscription delivery immediately without erasing relationship or notification history.
Path Parameters
Header Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Unmute a Task
/api/v1/tasks/{task_id}/subscription/muteIdempotently restores the caller's manual state to following.
Path Parameters
Header Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List current Task followers
/api/v1/tasks/{task_id}/subscribersReturns only active, currently authorized user Actors whose effective state is following. Muted, unfollowed, removed, suspended, and inaccessible identities are excluded.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
List Task attachments
/api/v1/tasks/{task_id}/attachmentsReturns the newest 100 linked files. Optional attachment_id values select up to 100 exact linked targets regardless of age; deleted, unlinked and private Discuss files are omitted after parent authorization.
Path Parameters
Query Parameters
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Path Parameters
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1·max 255Display filename, at most 255 UTF-8 bytes after NFC normalization.
It must not contain a path separator, null, or control character,
must not be . or .., and must not begin or end with whitespace or
a dot. A violating filename is rejected rather than rewritten.
Filenames never contribute to the server-generated object key.
string·max 255Server-detected from the object's leading bytes, not client-declared.
stringMalware-scan state. New uploads are scanned synchronously before
they become usable: only clean attachments may be linked, previewed,
or downloaded. quarantined attachments remain private and unavailable.
not_scanned is retained only for legacy migration visibility.
not_scannedpendingcleanquarantinedstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Start and assign a Task to the calling Actor
/api/v1/tasks/{task_id}/startTransitions the Task to the Project's preferred in-progress Status and
assigns it to the calling Actor in one idempotent, revision-checked,
audited transaction. A previous assignment period is closed rather
than erased. reassigned indicates that the caller replaced another
active assignee without disclosing that Actor through this command.
This server command never changes local Git state.
Path Parameters
Header Parameters
string·min 1·max 200Required when this operation uses browserSession; native bearer callers omit it because no ambient cookie is sent.
string·min 16·max 200Opaque client-generated key for safely retrying this operation.
Responses
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Atomically move a Task in workflow order
/api/v1/tasks/{task_id}/moveChanges a Task's Status and shared manual order in one transaction.
Neighbour anchors must be active Tasks in the destination Project and
Status group. A stale revision returns 409 revision_conflict; a
missing, archived, or out-of-group anchor returns 409 anchor_not_found. Both conflicts carry the current Task so clients
can re-anchor without an additional read.
Path Parameters
Header Parameters
Request Body
application/jsonstring <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>The active Task that must immediately precede the moved Task in the destination column.
string <uuid>The active Task that must immediately follow the moved Task in the destination column.
Responses
stringQuoted decimal optimistic-concurrency version.
objectMaterialized lifecycle policy of the entity's current status. Compare
stage_revision and definition_revision for staleness; behaviors
is the complete set for the entity kind, so clients never infer policy
from names or categories. Absent when the selection has no lifecycle
status. Resolved for a whole page with one batch lookup. Project list
rows carry identities and revisions only: stage_name and behaviors
are omitted there and returned by Project detail and the lifecycle
definition list.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 4·max 28Case-insensitive client input normalized to uppercase by the server.
Exactly the UI ticket reference {PROJECT_KEY}-{TASK_NUMBER} (for
example PRO-123); the positive Task number is canonical decimal
without leading zeroes.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·min 1Server-owned sortable order key within the Task's Project and Status. Clients render it but submit neighbour anchors when moving a Task.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
objectVersioned, server-validated rich-text document. The server accepts only nodes and marks on the Assign allowlist and rejects anything outside it; the client's installed editor extension set is never authoritative. Complexity is bounded at 32 levels of nesting and 50,000 nodes in addition to the per-field byte limits.
Accepted nodes: doc, paragraph, text, heading, bulletList,
orderedList, listItem, taskList, taskItem, blockquote, callout,
codeBlock, blockMath, horizontalRule, hardBreak, image, file, plus the
reference nodes userMention, projectReference, documentReference,
and taskReference. Accepted marks: bold, italic, underline,
strike, code, link.
A Task-description or Comment mutation accepts at most 100 distinct
canonical user identifiers across its userMention nodes. Repeated
mentions of the same user count once.
image and file name an Assign attachment through
attrs.attachmentId and carry no URL and no bytes: attachments travel
only through the attachment upload and download operations, and a
signed URL is minted per request after a fresh authorization check
rather than stored in content. A request whose image or file node
omits attachmentId, or carries a URL-bearing attribute, is rejected.
callout has block children and exactly attrs.kind and attrs.icon.
Kind is callout, note, tip, important, warning, or caution.
Icon is null for the default Lucide icon, an emoji of at most 64 UTF-8
bytes, an allowlisted lucide:name token to override it, or an empty string
to hide it. Unknown Lucide names are rejected. HTML, URLs and image
data are not accepted as icons. Callouts are additive in schemas 1 and 2.
blockMath stores a required string attrs.latex; rendered math HTML
and renderer settings are not persisted. Schema 1 retains the existing node contract; schema 2 additionally admits tables.
Checklists, attachment blocks, display equations, underline, and
projectReference were added additively, so every
previously stored document is still valid and no migration is
required.
Schema 2 additionally accepts table, tableRow, tableCell and tableHeader. A table has tableRow children; a row has tableCell/tableHeader children. Cells contain Assign blocks, starting with a paragraph; nested tables are rejected. Cells accept colspan/rowspan (integers 1–64, default 1), colwidth (null or one integer 24–2000 per spanned column), and align (null, left, center or right). Tables/rows have no attrs, marks or text; cells have no marks/text or other attributes. The occupancy grid must be rectangular with no overlap, holes or spans beyond its rows. Limits are 1000 rows, 64 logical columns and 10000 physical cells, still subject to each field's byte budget and global node/depth limits. Schema 1 rejects all four table nodes. Rich tables exchange through the named assign-table Markdown JSON fence; simple tables use GFM pipes.
objectRevision-bound derived convenience text. It is null when the body is shorter than 300 normalized characters, generation is pending, or the stored projection is stale. It is never evidence or a replacement for description content.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string <date-time>Server-written instant when the Task last entered a done-category Status; null while open or unavailable for a pre-migration record.
string <date-time>Instant the current terminal episode began; cleared when the Task becomes active again.
string <uuid>Actor that started the current terminal episode; null only for migrated or trusted automated provenance gaps.
stringTerminal outcome for the current resolved episode; null for active Tasks.
completedcancelledstring <uuid>[]·max 20Task collections include the complete assignment identifier set; an empty array means no labels. Non-collection responses may omit this field; use the target-label read when absent.
objectPresent only on a mutation response when the server created an undoable command. Read responses omit it.
string <date-time>Fixed retention deadline after which the asynchronous purge sweeper may redact Task content; null outside trash and after purge.
string <date-time>Tombstone creation instant. A purged Task retains only stable reference metadata and cannot be restored.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
Admit an independent Task collaboration-presence lease
/api/v1/tasks/{task_id}/collaboration-sessionsEvaluates the caller's current Task permission and creates an
independent session for this browser client. A caller with read-only
access receives role viewer; a caller who may edit receives editor.
The opaque admission_token lasts five minutes, is scoped to this
Task, actor, and session, and authorizes nothing on this HTTP API.
Each admission has its own token and exclusive connection lease, so
another tab cannot invalidate it. The connected relay renews the
lease; disconnected sessions expire through bounded cleanup.
The lease admits the browser-only Task description relay. Raw Yjs updates, checkpoints and caret awareness are not REST or SDK payloads. Task creation drafts, Comments, archived and trashed Tasks are excluded.
X-Assign-Document-Schema defaults to 1. An editable schema 2 admission promotes only this resource's envelope through its normal revision transition, preserving opaque updates, checkpoints and replica generation. Existing schema 1 resources continue to accept schema 1 clients. Once promoted, schema 1 admission and already admitted schema 1 writes fail with document_schema_version_unsupported. Invalid header values fail with document_schema_version_unsupported. Project permissions remain authoritative.
Path Parameters
Header Parameters
string·min 43·max 43Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
string <uuid>Task replica generation; an ordinary description replacement invalidates retained updates from the old generation.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
End the caller's Task collaboration-presence lease
/api/v1/tasks/{task_id}/collaboration-sessions/{session_id}Ends only the caller's own session. Repeating a successful end remains
successful. A nonexistent or somebody else's session returns 404 so
the operation cannot disclose collaborator presence. No Workspace
event or Activity item is written.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.
integer·min 1Seconds until the client may retry.
integer·min 0Delay in seconds before retrying, when an expected maintenance end is known.
string·const no-storePrevents storage of error responses by clients and intermediaries.
string·min 1·max 200Correlation identifier for the request.
string·const nosniffPrevents user agents from MIME-sniffing the response.