Update Project metadata, planning dates, path, visual identity, or visibility
Update Project metadata, planning dates, path, visual identity, or visibility
/api/v1/projects/{project_id}Applies an optimistic compare-and-swap to exactly one of name, path,
description, url, visual_identity, visibility, or owner_actor_id, or sends the complete nullable start_on/target_on date pair. If-Match must carry the revision last observed by
the client. Send visual_identity: null to restore the default marker.
Setting visibility to public requires the Workspace's public-publishing billing
entitlement; denial returns 403 paid_workspace_required. Unpublishing remains
available subject to normal authorization. Public reads return the existing privacy-safe
404 while that entitlement is absent, without changing stored visibility or content.
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.
string·min 16·max 200Opaque client-generated key for safely retrying this operation.
Request Body
application/jsonbooleanProject managers may persist whether cancelled-type Board columns are shown.
string <date>Must be sent with start_on; when both values are present, it cannot precede start_on.
A single allowlisted Lucide icon name or fully-qualified Unicode Emoji 17.0 sequence.
stringPublishing is permitted only for the Project owner or a Workspace administrator.
workspaceprivatepublicstring <uuid>Transfers the owner/lead to an active Workspace member. Only the current owner or a Workspace administrator may use it.
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>Current Actor that owns the Project and serves as its lead. The owner and Workspace administrators may publish or unpublish it; governed owner transfer is separately revision-checked.
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.
string·min 1·max 63Editable, Workspace-unique URL segment generated from the Project name at creation.
string·max 500Optional plain-text Project summary. It is returned only to authenticated Project readers.
string <uri>·max 2048Optional absolute HTTP or HTTPS Project link. It is returned only to authenticated Project readers.
string <uuid>Selected Workspace Project-state identifier. It remains present when the optional capability is disabled, but cannot be changed until re-enabled.
Optional decorative marker. A null value uses the client fallback without persisting it.
stringPrivate Projects require explicit Project membership except for governed Workspace owner/admin access. Public affects only the sanitized anonymous projection; authenticated access remains policy-checked.
workspaceprivatepublicstring <uuid>Opaque unlisted identifier present only while the Project is public.
booleanProject-owned Board preference. False omits cancelled-type columns from the ordinary Board.
integer·min 0Present on Workspace Project list reads. Exact count of all Tasks excluding archived, trashed and purged Tasks; independent of Task pagination. Includes completed and cancelled Tasks. Mutation and detail responses may omit this aggregate.
string <date-time>Latest updated_at among the Tasks included in task_count. Omitted when no active Tasks exist or the aggregate was not read.
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.