workspaceId, audience, the guarded-write preconditions, and why (see Create Artifact, Publish Version, Append Rows, Create Task).
Auth: Authorization: Bearer tr_... (an account API key). {id} is always the workspace UUID: slugs are not resolved, and a non-UUID id is a 400.
The operator dashboard uses mirrors under
/v0/operator/workspaces… with a browser session. The operator surface adds artifact create/list, folder rename and delete, GET …/pins, …/browser-context, a browser reader (…/activity, …/activity/peek, …/activity/ack), and the browser-tab routes (…/views, …/views/{viewId}/pair|context|poll|navigation-ack|disconnect). It mirrors …/sessions and omits the key-bound load, view, view/open, and changes routes.
Roles and capabilities
Every workspace response that describes the workspace carries your liverole (admin | editor | viewer), membership (internal | external), audiences, and capabilities. Internal members see internal and shared content; external members see only shared.
deleteContent covers deleting files and folders and restoring them from the trash. deleteWorkspace covers deleting the workspace and restoring it.
Shared errors
Why on every write
Every agent write to workspace content stateswhy: one sentence on what the person you work for is trying to accomplish, in their terms, not a description of the edit. “Set launch prices the team can defend to finance” is a goal; “Update row 4 of the pricing table” is not. It is a body field on JSON writes, a form field on multipart uploads, and a query parameter on DELETE /v0/artifacts/{id} and DELETE /v0/artifacts/{id}/versions/{versionId}. The change feed and Sessions show it to whoever comes next. Pins and lease touches record no change and take no why; edits a person makes in the dashboard never need one.
Standalone artifacts accept
why and do not require it. During the deprecation window, writers ignore the old workspaceSessionId field, and POST /v0/workspaces/{id}/sessions/{sessionId}/end (workspace_session_end, rip workspace session end) answers 400 SESSION_END_RETIRED: sessions record themselves, and a note for the next agent is a markdown artifact published with handoff: true.