CLI
Bearer-authenticated, code-addressed projections and commands for the Assign CLI.
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
Responses
stringUppercase-normalized ticket prefix used to form human-readable Task
references (for example ASSIGN-42). Unique per Workspace and
immutable after creation; not a substitute for the opaque id.
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.
Create a Task in a Project resolved by immutable key
/api/v1/cli/projects/{project_code}/tasksCreates a Task through the canonical Task workflow using the Project key
and Workspace defaults. Optional description Markdown is converted only
through the supported safe Markdown profile. Requires assign:write and
an idempotency key; Task identity remains code-addressed.
Path Parameters
Header Parameters
Request Body
Responses
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·min 1·max 64Case-insensitive client input normalized to uppercase by the server. A code is unique across Projects, Tasks, and Documents in one Workspace. Internal UUIDs are not a CLI identifier.
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 Documents in the credential-bound Workspace
/api/v1/cli/documentsReturns top-level, non-archived Document metadata, optionally limited to one Project key.
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.
Read a Document by its canonical path
/api/v1/cli/documents/{document_path}Returns metadata and at most 65,536 characters of server-extracted text; truncated reports whether more text exists.
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.
Read the caller's bounded CLI My Work projection
/api/v1/cli/my-workReturns the caller's active assigned Tasks (not done) in the bearer
token's Workspace. Rows are ordered and paginated by the server; no
UUID is returned. A token is audience-bound to this API host and must
carry assign:read.
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.
Search Tasks and Documents in the token-scoped Workspace
/api/v1/cli/searchSearches only Task and Document projections visible to the bearer
principal. q is trimmed before validation and must contain 1–200
Unicode characters. Results use an opaque server cursor, default to
50, and never exceed 100. Resource codes are the only identifiers
returned; IDs remain internal to the API implementation.
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.
Create a short-lived MCP token for the local CLI bridge
/api/v1/cli/mcp/tokenExchanges the caller's CLI OAuth or personal API-token authority for a non-refreshable MCP access token. The requested Workspace must match the authenticated principal, and requested scopes may only narrow the parent credential. The grant records its parent credential so parent expiry or revocation immediately invalidates the derived token.
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 a Milestone by code within the bearer Workspace
/api/v1/cli/milestones/{milestone_code}Resolves the code's Project key by indexed authorized lookup in the token-scoped Workspace, then uses the shared typed Milestone resolver. Includes archived Milestones and canonical Task-derived progress. ASCII casing normalizes; no generic resource dispatch, collection scan or domain write. Existing UUID and browser/native operations remain unchanged.
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 | null·min 1·max 64Optional stable Workspace Milestone stage ID. Must select an active stage whose category agrees with status; null clears the selection. An explicit legacy status update without stage_id clears a custom selection.
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 | null·max 19Stable Project-local positive signed-64-bit number as canonical decimal text (maximum 9223372036854775807), independent of Task numbering and rank. Null or absent while a historical Milestone awaits reference backfill; never derive it client-side.
string | null·max 29Canonical uppercase Project-key Milestone reference, for example FRS-M1. Stable across rename, reorder and archive/restore. Null or absent with milestone_number during historical backfill. UUID selectors and foreign keys remain authoritative; knowing a code grants no access.
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 Task by code
/api/v1/cli/tasks/{task_code}Resolves the uppercase-normalized Task code within the token-scoped
Workspace. The revision field and the ETag header carry the
current revision that the revision-checked lifecycle operations
expect in If-Match. A Task the bearer cannot read is
indistinguishable from a missing one.
Path Parameters
Responses
stringQuoted decimal optimistic-concurrency version.
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·min 1·max 64Case-insensitive client input normalized to uppercase by the server. A code is unique across Projects, Tasks, and Documents in one Workspace. Internal UUIDs are not a CLI identifier.
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 bearer Actor
/api/v1/cli/tasks/{task_code}/startResolves the uppercase-normalized Task code within the token-scoped
Workspace, transitions it through the canonical workflow to the
Project's active Status, and assigns it to the bearer Actor in one
idempotent, revision-checked, audited transaction. An existing
assignment is closed rather than erased. reassigned tells the CLI
whether to warn; no prior Actor identifier is disclosed for that use.
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.
Apply the canonical completion action to a Task
/api/v1/cli/tasks/{task_code}/doneApplies the Project completion policy in one idempotent,
revision-checked, audited transaction. When review is required, an
active Task enters the default review Status and only an authorized
reviewer can invoke this operation again to enter the default done
Status. Definition-of-Done and transition guards remain server-owned.
The completing Status comes from the lifecycle completion rule: one
applicable Status that counts as completed is used directly; several
answer 409 completion_target_required with the choices
(LifecycleCompletionChoices) until the caller sends target_status_id. A Status that does not count as
completed answers 422 completion_target_invalid.
Path Parameters
Query 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.
Reopen a completed Task
/api/v1/cli/tasks/{task_code}/reopenMoves a done Task to the Project's default active Status in the canonical, revision-checked, idempotent, audited workflow.
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.
Read a bounded Task context packet
/api/v1/cli/tasks/{task_code}/contextReturns server-rendered Markdown in a fixed section order. compact
is capped at 16 KiB, 20 related items, and 10 comments; full is
capped at 64 KiB, 100 related items, and 50 comments. The result
marks truncation, unavailable providers, and inaccessible material.
Resource content is untrusted and is never executable instruction.
Path Parameters
Query Parameters
Responses
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.
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 Task comments by Task code
/api/v1/cli/tasks/{task_code}/commentsReturns canonical comments as supported Markdown in creation order. Tombstones retain their position with an empty body.
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.
Add a Markdown comment to a Task resolved by code
/api/v1/cli/tasks/{task_code}/commentsConverts supported Markdown into the canonical Comment document and appends it through the normal authorization, audit, event, and idempotency path.
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.