Skip to main content
A workspace is the one home for a project’s artifacts, tables, flat folders, and tasks. These routes manage the workspace itself and what an agent reads when it arrives. Project content is written through the ordinary artifact, table, folder, and task routes with workspaceId, the guarded-write preconditions, and why (see Create Artifact, Publish Version, Append Rows, Create Task). Auth: Authorization: Bearer tr_... (an account API key). {id} (and workspaceId on every other route and tool) is the workspace’s id or slug, in any case. A slug is looked up among the workspaces you reach (yours, your teams’, and those you are a member of). One none of them has answers 404 WORKSPACE_NOT_FOUND, as an unknown id does; one two of them share answers 409 AMBIGUOUS_REFERENCE listing each candidate’s id: use the id. The operator dashboard’s routes take the id only. The operator dashboard uses mirrors under /v0/operator/workspaces… with a browser session. The operator surface adds artifact create/list, GET …/pins, …/browser-context, a browser reader (…/activity, …/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, /v0/views/open, and changes routes.

Roles and capabilities

Everyone in a workspace sees all of it: files, tables, folders, tasks, outputs, jobs, history and the trash. Every workspace response that describes the workspace carries your live role (admin | editor | viewer), guest, and capabilities. guest is true when you were added to the workspace, rather than owning it or being in its team. Admin comes only from ownership or the team: the owner and the owning team’s owner and admins are admins; other team members are editors. People added or invited through Members and Invites are guests, as an editor (the default) or a viewer. deleteContent covers deleting files and folders and restoring them from the trash. share covers adding or inviting people, changing their role, removing them, and setting a file’s public link. Listing members needs only read. manageWorkspace covers the name, description and history setting. deleteWorkspace covers deleting the workspace and restoring it. Sharing is by workspace: no item has an audience of its own. A write that sends audience is refused 400 INVALID_FIELD: “Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace.”

Shared errors

Why on every write

Every agent write to workspace content takes why: one sentence on what the person you work for is trying to accomplish, in their terms, not a description of the edit. Moving a task along (start, stop, complete, cancel, reopen, a move in the queue, a later result on a Done task), an output on a task and settling an output take it optionally: the record carries its own reason, and a why sent is recorded. A message needs none. “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 every write, deletes included (DELETE /v0/artifacts/{id}, DELETE /v0/versions/{versionId}), and a form field on multipart uploads. Every other call accepts it too, a GET in its query: it is not recorded there, and Tokenrip keeps it with the record of the call. The change feed and Sessions show it to whoever comes next. Pins record no change: a why sent is accepted, not recorded; edits a person makes in the dashboard never need one. Standalone artifacts accept why and do not require it. There is no session to start or end: sessions record themselves, and open work stays in tasks. The retired workspaceSessionId field is refused as an unknown field on workspace, artifact, table, folder and trash writes.