Workspaces

The workspace.* family (12 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Grantworkspace.access.grant

: grant an actor entry to a workspace of THIS organisation.

Call POST /v/workspace.access.grant with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Revokeworkspace.access.revoke

: revoke an actor’s entry to a workspace.

Call POST /v/workspace.access.revoke with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Upsertworkspace.agentConfig.upsert

(DEFERRED court-gated). 1:1 (workspace_id) upsert, set-if-present merge. cloud_fire_token_enc is already-encrypted. Mints wsagent_.

Call POST /v/workspace.agentConfig.upsert with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Upsertworkspace.aiConfig.upsert

(DEFERRED court-gated AI-credential). 1:1 (workspace_id) upsert, set-if-present merge. Stores already-encrypted blobs. Mints wsaicfg_.

Call POST /v/workspace.aiConfig.upsert with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Createworkspace.create

Mints a SIBLING workspace under the AUTHENTICATED caller’s organisation (resolved from the caller’s current workspace, never a param). It does NOT seed a new org or owner (C1: founding is opbox initiate, not this verb). The new workspace is ACTIVE. A HUMAN gate (mirror org.membership.set, CC-OPBOX 49): minting a scope-root is a human firm-owner act, not an agent one.

Input { name } (fields ending in ? are optional)

Call POST /v/workspace.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.create.

Deleteworkspace.delete

SOFT-archives a workspace (status=‘ARCHIVED’ - never a hard DELETE, so the audit chain + every FK off the scope-root survive). REFUSES archiving the org’s LAST non-archived workspace (a LAST_OVERSEER-style guard - never strand the org with no live workspace). Idempotent on an already-ARCHIVED workspace. workspaceId defaults to the caller’s current workspace.

Input { workspaceId? } (fields ending in ? are optional)

Call POST /v/workspace.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.delete.

Setworkspace.ext.set

The 1:1 (workspace_id) workspace_ext config upsert that folds the four workspaceExt.upsert sites (invoice settings / jurisdiction / processing-role / workspace-settings). PARTIAL: only the fields PRESENT in the payload are written; absent fields are left untouched on UPDATE and take the column default on first INSERT. The nullable strings discriminate absent (leave) vs null (clear) vs set. { workspaceId?, settings?, jurisdiction?, processingRole?, taxInvoiceBaseCurrency?|null, fxRateSource?|null, defaultInvoiceBrandingThemeId?|null, dataControllerName?|null, dataControllerEmail?|null }.

Call POST /v/workspace.ext.set with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.ext.set.

Getworkspace.get

Returns ONE workspace’s registry columns {id, name, organisationId, status} (holding D - the internals stay unexposed). workspaceId defaults to the caller’s current workspace; a named target must be a same-org sibling. Org-scoped.

Input { workspaceId? } (fields ending in ? are optional)

Call POST /v/workspace.get with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.get.

Listworkspace.list

Lists the caller’s ORGANISATION’s workspaces (WHERE organisation_id = org_of_workspace(ctx)) - the registry columns {id, name, organisationId, status} only (holding D). Org-scoped: a caller never sees another org’s scope-roots.

Input {} (fields ending in ? are optional)

Call POST /v/workspace.list with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.list.

Createworkspace.skill.create

(DEFERRED background-sync). Unique (workspace_id, skill_key): ON CONFLICT DO NOTHING + re-read. { workspaceId?, skillKey, provenance, documentId, baselineSourceAddon?, baselineVersion?, baselineHash?, hasOverlay?, metadata? }. Mints wsk_.

Call POST /v/workspace.skill.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.skill.create.

Updateworkspace.skill.update

(DEFERRED). Partial PATCH fenced by id+workspace. Supports the overlayPatch / overlayStaleSince null-clear, baselineVersion absolute set OR increment. { id, provenance?, hasOverlay?, overlayPatch?|null, overlayStaleSince?|null, baselineHash?, baselineVersion?, baselineVersionIncrement?, documentId?, metadata? }.

Call POST /v/workspace.skill.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.skill.update.

Updateworkspace.update

Renames a workspace. workspaceId defaults to the caller’s current workspace; a cross-workspace rename must name a same-org sibling (RLS keys reads off the session; the explicit org predicate fences the write to the caller’s org). Touches updated_at.

Input { workspaceId?, name } (fields ending in ? are optional)

Call POST /v/workspace.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool workspace.update.