Workspaces
Workspace lifecycle, membership, and invitations.
List access-filtered Workspace activity
/api/v1/workspaces/{workspace_id}/activityReturns a newest-first, cursor-bounded page of meaningful work changes.
Activity is projected from immutable domain events at read time using
the caller's current access. Only registered activity types appear:
progress, ownership, deadline, priority, milestone, description,
blocking-dependency, comment, document, Project and Milestone changes.
Personal preferences (following or muting), ordinary reactions,
ordinary title corrections, configuration, security, session,
identity, membership, integration, and Agent execution events never
appear here; an ordinary edit remains available in that item's own
history. action is a stable localization key, not a rendered
sentence, and summary never includes comment, Document, or other
free-form content. Events from one command or one editing session
collapse into a single item: count says how many events it
represents and affected lists up to 25 of the resources a bulk
change touched. Private Project resources are filtered before
pagination and grouping, so items, cursors, has_more, and
affected cannot disclose inaccessible work. limit bounds the
events examined, so a page may hold fewer items than limit; only
has_more says whether history continues. provenance distinguishes
mediated actions while preserving the stable Actor; a group carries
the least direct classification among its members.
Optional paired day and time_zone select one civil day's inclusive
local midnight to exclusive next midnight, including DST changes.
The indexed time range applies before pagination and counting; cursors
are bound to that interval. Existing 90-day retention still applies.
Path Parameters
Query Parameters
string <date>Civil date; requires time_zone. Invalid or unpaired inputs return 400 invalid_request.
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.
Path Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Path Parameters
Header Parameters
Request Body
application/jsonResponses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Read Workspace Knowledge indexing settings and lifecycle state
/api/v1/workspaces/{workspace_id}/knowledge-settingsPath Parameters
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
booleanDesired enablement defaults to the active paid-plan Knowledge entitlement unless explicitly changed. Empty included_projects keeps indexing and retrieval inactive.
booleanTrue only when the Workspace has the active workspace_knowledge entitlement.
Update desired Workspace Knowledge indexing settings
/api/v1/workspaces/{workspace_id}/knowledge-settingsPath Parameters
Header Parameters
Request Body
application/jsonbooleanSaves an explicit enablement choice that survives billing changes. Enabling requires the active Knowledge entitlement and may precede Project selection.
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
booleanDesired enablement defaults to the active paid-plan Knowledge entitlement unless explicitly changed. Empty included_projects keeps indexing and retrieval inactive.
booleanTrue only when the Workspace has the active workspace_knowledge entitlement.
Redirect to a short-lived inline S3 URL for the Workspace icon
/api/v1/workspaces/{workspace_id}/icon/contentPath Parameters
Responses
Create the native caller's first Workspace
/api/v1/mobile/workspaces/bootstrapRuns the same first-Workspace creation service and serialized account membership check as browser bootstrap. Existing memberships cause 409. Returns the Workspace without creating, switching or setting browser cookies. The native app selects the returned Workspace explicitly. No additional paid-plan or general Workspace-creation operation is admitted.
Request Body
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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 Workspace AI access policy
/api/v1/workspaces/{workspace_id}/ai-access-policyReturns the revisioned policy checked on every MCP authorization and Workspace tool request. An absent stored row defaults to enabled at revision zero.
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.
Update the Workspace AI access policy
/api/v1/workspaces/{workspace_id}/ai-access-policyEnables or disables external AI access for the current Workspace. Disabling takes effect for existing MCP grants on their next request without revoking those grants in another Workspace.
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.
List Workspace MCP service credentials
/api/v1/workspaces/{workspace_id}/mcp-service-credentialsLists at most 100 active, unexpired named service credentials. Raw credential values are never returned.
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.
Create a Workspace MCP service credential
/api/v1/workspaces/{workspace_id}/mcp-service-credentialsCreates a non-human service actor and a Workspace-bound MCP credential.
The raw credential is returned exactly once. An empty project_ids
array permits every currently visible Project in the Workspace; a
non-empty array narrows the credential to those Projects.
Path Parameters
Header Parameters
Request Body
application/jsonstring[]·min 1·max 37assign:activity:readassign:agents:readassign:agents:writeassign:attachments:readassign:attachments:writeResponses
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.
Revoke a Workspace MCP service credential
/api/v1/workspaces/{workspace_id}/mcp-service-credentials/{credential_id}Immediately refuses the credential on every instance while retaining its service actor for audit history.
Path Parameters
Header Parameters
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
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 the caller's first Workspace
/api/v1/workspaces/bootstrapCreates the first Workspace, owner membership, and Actor for a signed-in account that has no active Workspace memberships. The caller selects both the visible name and canonical URL segment.
Success rotates the account-only session into the new Workspace and
replaces both browser-session cookies. Concurrent requests are
serialized so at most one first Workspace is created for an account.
A caller that already has a Workspace receives 409 and must use the
normal session-switch operation instead.
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.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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.
Get native account Workspace-creation options
/api/v1/mobile/workspace-creation-optionsRequires a first-party native bearer; browser cookies are not accepted. Paid choices are informational until native paid-checkout admission is qualified. Returns the signed-in human account's Free Workspace claim state and currently purchasable paid choices. Membership and the selected Workspace role do not affect this account-level eligibility. The Paid choices are present only when the configured provider and every required immutable local catalog mapping are available.
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
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 Free Workspace with a native account
/api/v1/mobile/workspacesRequires a first-party native bearer; browser cookies are not accepted. Creation does not select a Workspace or issue browser cookies. Claims and creates the signed-in human account's one active Free Workspace, provisioning the Workspace, owner membership, Actor, default workflow, claim, and events in one transaction. Membership and role in the selected Workspace do not grant or deny this account-level command.
The optional slug selects the canonical URL segment. When omitted,
Core generates a collision-safe value from the name.
Creation does not switch the calling session onto the new
Workspace. Changing scope is PUT /api/v1/auth/session/workspace,
which always rotates the session and CSRF secrets; doing it as a side
effect here would rotate them invisibly.
Header Parameters
Request Body
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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.
Get account Workspace-creation options
/api/v1/workspace-creation-optionsReturns the signed-in human account's Free Workspace claim state and currently purchasable paid choices. Membership and the selected Workspace role do not affect this account-level eligibility. The Paid choices are present only when the configured provider and every required immutable local catalog mapping are available.
Responses
string·const no-storePrevents storage of error responses by clients and intermediaries.
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 Workspace
/api/v1/workspacesClaims and creates the signed-in human account's one active Free Workspace, provisioning the Workspace, owner membership, Actor, default workflow, claim, and events in one transaction. Membership and role in the selected Workspace do not grant or deny this account-level command.
The optional slug selects the canonical URL segment. When omitted,
Core generates a collision-safe value from the name.
Creation does not switch the calling session onto the new
Workspace. Changing scope is PUT /api/v1/auth/session/workspace,
which always rotates the session and CSRF secrets; doing it as a side
effect here would rotate them invisibly.
Header Parameters
Request Body
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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 Workspace-wide workflow Statuses
/api/v1/workspaces/{workspace_id}/statusesReturns a cursor-bounded, workflow-ordered page of Statuses whose
project_id is null and which therefore apply to every Project in
the Workspace. Active members with work:read may read the catalog.
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 Workspace-wide workflow Status
/api/v1/workspaces/{workspace_id}/statusesAppends a Status that applies to every Project in the Workspace.
This requires workspace:manage: unlike a Project-local Status, the
new catalog entry changes how all Workspace work is categorized.
Path Parameters
Header Parameters
Request Body
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>Null for a Workspace-wide Status applicable to every Project.
stringCanonical lifecycle meaning. Custom labels remain presentation; completed and cancelled are terminal.
backlogunstartedstartedcompletedcancelledstringOptional shared Tailwind family or pinned shade, retaining legacy six-digit hex colors. A bare family uses step 500 for Status markers; null inherits the lifecycle default.
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 the typed lifecycle behavior registry
/api/v1/lifecycle-behaviorsReturns every behavior key a stage can enable, the entity kinds it applies to and the domain consumer that owns its effect. The list is static for a server version and safe to cache briefly.
Resolve the status that completes an entity of a kind
/api/v1/workspaces/{workspace_id}/lifecycle-completion-targetsRequires Workspace read access. Completion is never inferred from
labels. With one completing status the response names it. With several
and no target_status_id the response is 409 completion_target_required
listing the choices, so the caller must name one. An explicit target
that does not count as completed is 422 completion_target_invalid;
a kind without any completing status is 422 completion_target_unavailable.
List lifecycle definitions with stages, policies and statuses
/api/v1/workspaces/{workspace_id}/lifecycle-definitionsRequires work:read. Returns the Workspace's definitions (optionally one kind) with every stage's complete typed behaviors and bound statuses in presentation order, so selectors and settings render from one read. The catalog is bounded by the lifecycle limits (20 definitions per kind, 100 stages per definition, 500 statuses per definition), so it is not paged. Behaviors that do not apply to the kind are absent.
Preview moving statuses of a lifecycle definition
/api/v1/workspaces/{workspace_id}/lifecycle-definitions/{definition_id}/mapping-previewsRequires Workspace management authority. Validates that every source
status has exactly one same-kind, same-Workspace, active destination
that is not itself retired, and returns bounded per-status impact counts
(capped at 10,000, truncated when reached) and the behavior keys whose
value would change. If-Match binds the definition revision; a mismatch
is 409 revision_conflict. Nothing is written. Pass the returned
destination_revisions and source_revision back to apply.
Path Parameters
Header Parameters
Request Body
application/jsonobjectSource status ID to destination status ID. A source mapped to itself keeps its ID and entities. Sources are exactly the keys.
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
Apply a previewed status mapping as a durable migration job
/api/v1/workspaces/{workspace_id}/lifecycle-definitions/{definition_id}/mapping-applicationsRequires Workspace management authority and an Idempotency-Key; a
repeat with the same key and mapping returns the original job and a
different mapping is 409 idempotency_key_conflict. The request is
re-validated against If-Match and destination_revisions
(409 lifecycle_preview_stale or revision_conflict), and material
behavior changes or a default replacement need acknowledged: true
(409 lifecycle_acknowledgement_required). Scopes within the
1,000-entity synchronous limit are moved before the response
(200, status completed, or 202 when a retry is pending); larger
scopes return 202 and a background worker moves bounded pages. A
Workspace has one applying job (409 lifecycle_migration_pending).
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/jsonobjectSource status ID to destination status ID. A source mapped to itself keeps its ID and entities. Sources are exactly the keys.
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.
stringstring <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.
Read a lifecycle migration job
/api/v1/workspaces/{workspace_id}/lifecycle-migrations/{job_id}Requires Workspace management authority. Returns pending, processing, retry, completed or failed state with progress and a safe error code.
Path 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.
Resume a failed lifecycle migration job
/api/v1/workspaces/{workspace_id}/lifecycle-migrations/{job_id}/retryRequires Workspace management authority. Makes a failed job runnable again, keeping pages already moved; any other state is 404 not_found.
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.
Read configured Milestone stages
/api/v1/workspaces/{workspace_id}/milestone-lifecycleRequires work:read. Returns at most 100 retained stages in presentation order. A Workspace without a saved catalog returns the four default stages at revision 1.
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.
Configure Milestone stages
/api/v1/workspaces/{workspace_id}/milestone-lifecycleRequires workspace:manage. Atomically replaces the bounded catalog under If-Match. Every semantic category retains active coverage. Referenced IDs and categories cannot be removed or changed. Archiving an in-use stage requires a same-category active replacement; at most 1000 active Milestones are moved atomically. Archived Milestones retain historical selections. Conflicts include revision_conflict, milestone_stage_in_use and lifecycle_migration_too_large. Names are trimmed; no transition graph is introduced.
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
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 former member
/api/v1/workspaces/{workspace_id}/membersReactivates the membership of somebody who was removed or who left.
It takes a user_id an administrator has already seen in the member
list, and it is not a path for net-new people.
There is deliberately no address input. An endpoint that resolved an arbitrary email to an account would answer, for any caller who can manage members, whether that address is registered with Assign. Net-new people join through invitations, which prove control of the mailbox instead.
Reactivating an already-active membership is idempotent.
Path Parameters
Header Parameters
Request Body
Responses
stringQuoted decimal optimistic-concurrency version.
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.
stringviewer reads the Workspace and its work and writes nothing. admin
holds the same capabilities as owner; the only owner-reserved
operation is archiving the Workspace, and a Workspace must always
retain at least one active owner.
owneradminmemberviewerstringA membership that stops being active has its sessions in this
Workspace revoked immediately. removed retains the row and the
member's Actor so past work stays attributable.
invitedactivesuspendedremovedleftstring·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 Workspace
/api/v1/workspaces/{workspace_id}Returns the Workspace the caller's session is scoped to. Any active member may read it.
An archived Workspace is visible only to an owner, so un-archiving stays discoverable; every other member sees the same not-found response an absent Workspace produces.
Path Parameters
Responses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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.
Rename, change the URL, or restore a Workspace
/api/v1/workspaces/{workspace_id}Changes exactly one of name, slug, or archived. Renaming and URL
changes require the workspace:manage capability; archived: false
restores an archived Workspace and is the only mutation an archived
Workspace accepts.
archived: true is rejected here — archiving is
DELETE /api/v1/workspaces/{workspace_id}, which additionally
requires an owner and recent authentication.
slug is the canonical Workspace URL segment. It must be unique and
use lowercase letters, numbers, and interior hyphens only.
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/jsonResponses
stringQuoted decimal optimistic-concurrency version.
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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.
Archive a Workspace
/api/v1/workspaces/{workspace_id}Archives the Workspace. Requires an owner and authentication within the last 15 minutes, so a borrowed session cannot pull a Workspace out from under its members.
No data is deleted. Every session scoped to the Workspace is
revoked in the same transaction, the Workspace disappears from the
default Workspace list, and every Workspace-scoped route answers
not-found — except an owner's read and the restoring PATCH.
Archival is therefore a real access boundary, not a display flag, and
it is reversible.
A caller's last active Workspace cannot be archived. Account-only
sessions are reserved for first-Workspace onboarding, so an existing
scoped account cannot return to that state by archiving its Workspace.
That case answers 409 last_workspace.
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·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.
Change a member's role or state
/api/v1/workspaces/{workspace_id}/members/{member_id}Changes role, state, or both. An omitted field keeps its current
value. state moves between active and suspended; suspending a
member revokes their sessions in this Workspace immediately.
Promotion to owner is permitted.
Demoting, suspending, or otherwise removing the last active owner
is refused 409 last_owner. A caller may not change their own
membership: self-demotion and self-suspension have no legitimate use
and both produce a lockout the caller cannot then undo, so they answer
422 self_membership_mutation.
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/jsonResponses
stringQuoted decimal optimistic-concurrency version.
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.
stringviewer reads the Workspace and its work and writes nothing. admin
holds the same capabilities as owner; the only owner-reserved
operation is archiving the Workspace, and a Workspace must always
retain at least one active owner.
owneradminmemberviewerstringA membership that stops being active has its sessions in this
Workspace revoked immediately. removed retains the row and the
member's Actor so past work stays attributable.
invitedactivesuspendedremovedleftstring·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.
Remove a member
/api/v1/workspaces/{workspace_id}/members/{member_id}Ends the membership. The row is retained in a removed state and the
member's Actor is retained, so past Task assignments, comments,
and events stay attributable to a real identity.
The member's sessions in this Workspace are revoked in the same
transaction, so access ends immediately rather than at next expiry.
Removing the last active owner is refused 409 last_owner, and a
caller may not remove themselves. Repeat removal answers 204.
Path Parameters
Header 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 invitations
/api/v1/workspaces/{workspace_id}/invitationsReturns one newest-first page of invitations in every state — pending, accepted, expired, and revoked. Neither the token nor its hash is ever returned; the token exists in exactly one response, the one that created it.
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.
Invite someone to the Workspace
/api/v1/workspaces/{workspace_id}/invitationsCreates an invitation and returns the plain token once. Only a
hash is stored, so the token cannot be recovered later and a database
disclosure is not replayable into Workspace access. Repeating the
request with the same Idempotency-Key replays the original
response, token included, which is how a client that lost the first
response recovers it.
role may be admin, member, or viewer — not owner.
Ownership carries the archive power and the last-owner invariant, and
is conferred by a deliberate membership change on somebody already
present rather than by whoever opens a link in a mailbox.
A second unexpired pending invitation for the same address is refused
409 invitation_pending rather than silently reissued, so the link
the recipient already received stays the live one. An address that
already belongs to an active member is refused 409 already_member,
which discloses nothing an administrator cannot read from the member
list. If the configured email provider cannot accept the invitation,
the transaction rolls back and the endpoint returns retryable
503 delivery_unavailable.
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 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.
Revoke an invitation
/api/v1/workspaces/{workspace_id}/invitations/{invitation_id}Withdraws a pending invitation, so its link no longer opens the
Workspace. Repeating it answers 204.
Revoking an accepted invitation is refused
409 invitation_not_pending: acceptance is not undone by revoking the
link that produced it, and removing the resulting member is a
separate, visible act.
Path Parameters
Header 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.
Resend an invitation
/api/v1/workspaces/{workspace_id}/invitations/{invitation_id}/resendReplaces an unaccepted invitation with a fresh seven-day invitation
and sends the new link to the same normalized address with the same
role. The previous link stops working only when delivery of the new
message succeeds and the transaction commits. A delivery failure
returns 503 delivery_unavailable and leaves the previous pending
invitation usable.
Accepted, expired, and explicitly revoked invitations cannot be resent and
return 409 invitation_not_pending. Repeating the request with the
same Idempotency-Key replays the same successful response without
sending another message.
Path Parameters
Header 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 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.
Accept an invitation
/api/v1/invitations/acceptRedeems an invitation token and joins the Workspace. Requires a
signed-in session: the invitation's address must equal the caller's
stored address exactly after normalization, so a forwarded message
cannot transfer the grant. A mismatch answers
403 invitation_recipient_mismatch. A live invitation proves control
of the matching mailbox: acceptance verifies that address atomically
with membership creation, without another verification email.
Idempotency is account-scoped because the caller may have an authenticated account-only session and no target-Workspace membership before this operation succeeds.
An expired invitation answers 410 invitation_expired. A revoked or
already-accepted one answers 409 invitation_not_pending. An unknown
token answers 404 — the same answer a swept expired token gives, so
the endpoint is not a token oracle.
Acceptance does not switch the calling session onto the joined
Workspace; that is PUT /api/v1/auth/session/workspace.
Header Parameters
Request Body
Responses
string <uuid>Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.
stringServer-generated canonical Workspace URL segment. Authorized Workspace managers can change it through the revisioned Workspace update operation.
string <date-time>When set, the Workspace is archived: no data was deleted, every session scoped to it was revoked, and its scoped routes answer not-found for everyone but an owner.
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.