> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> The /v0/workspaces routes: lifecycle, members, adoption, folders, pins, sessions, browser context, and the change feed.

A [workspace](/concepts/workspaces) is the one home for a project's artifacts, tables, flat folders, and tasks. These routes manage the workspace itself and the harness session. Project **content** is written through the ordinary artifact, table, folder, and task routes with `workspaceId`, `audience`, the guarded-write preconditions, and optional `workspaceSessionId` (see [Create Artifact](/api-reference/artifacts/create), [Publish Version](/api-reference/versions/publish), [Append Rows](/api-reference/table-rows/append-rows), [Create Task](/api-reference/tasks/create)).

**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`.

| Method | Path | MCP tool | CLI | Page |
| - | - | - | - | - |
| POST / GET | `/v0/workspaces` | `workspace_create` / `workspace_list` | `rip workspace create` / `list` | [Create](/api-reference/workspaces/create), [List](/api-reference/workspaces/list) |
| GET / PATCH | `/v0/workspaces/{id}` | `workspace_show` / `workspace_update` | `rip workspace show` / `update` | [Get](/api-reference/workspaces/get), [Update](/api-reference/workspaces/update) |
| POST / POST / DELETE | `/v0/workspaces/{id}/archive`, `/restore`, `/v0/workspaces/{id}` | `workspace_archive` / `workspace_restore` / `workspace_delete` | `rip workspace archive` / `restore` / `delete` | [Lifecycle](/api-reference/workspaces/lifecycle) |
| GET / POST / PATCH / DELETE | `/v0/workspaces/{id}/members[/{accountId}]` | `workspace_member_list` / `_add` / `_set_role` / `_remove` | `rip workspace member …` | [Members](/api-reference/workspaces/members) |
| POST | `/v0/workspaces/{id}/adopt` | `workspace_adopt` | `rip workspace adopt` | [Adopt](/api-reference/workspaces/adopt) |
| POST / PATCH / POST | `/v0/workspaces/{id}/folders`, `…/folders/{folderId}`, `…/folders/{folderId}/share-contents` | `folder_create { workspaceId }` / `folder_update` / `folder_share_contents` | `rip folder create --workspace` / `update` / `share-contents` | [Folders](/api-reference/workspaces/folders) |
| POST / DELETE | `/v0/workspaces/{id}/pins[/{artifactId}]` | `workspace_pin` / `workspace_unpin` | `rip workspace pin add` / `remove` | [Pins](/api-reference/workspaces/pins) |
| POST | `/v0/workspaces/{id}/load` | `workspace_load` | `rip workspace load --operation-id` | [Load](/api-reference/workspaces/load) |
| POST | `/v0/workspaces/{id}/sessions/{sessionId}/end` | `workspace_session_end` | `rip workspace session end` | [End Session](/api-reference/workspaces/end-session) |
| GET / POST | `/v0/workspaces/{id}/sessions/{sessionId}/view`, `…/view/open` | `workspace_view_context` / `workspace_view_open` | `rip workspace view context` / `open` | [View Context](/api-reference/workspaces/view-context), [View Open](/api-reference/workspaces/view-open) |
| GET / POST | `/v0/workspaces/{id}/changes`, `…/changes/ack` | `workspace_changes` / `workspace_changes_ack` | `rip workspace changes` / `ack` | [Changes](/api-reference/workspaces/changes), [Acknowledge](/api-reference/workspaces/ack) |

The operator dashboard uses mirrors under `/v0/operator/workspaces…` with a browser session. The operator surface adds artifact create/list, folder rename and removal, `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 omits the credential-bound `load`, `end`, `view`, `view/open`, and `changes` routes.

## Roles and capabilities

Every workspace response that describes the workspace carries your live `role` (`admin` | `editor` | `viewer`), `membership` (`internal` | `external`), `audiences`, and `capabilities`. Internal members see `internal` and `shared` content; external members see only `shared`.

| Capability | Internal admin | Internal editor | External editor | External viewer |
| - | - | - | - | - |
| `read`, `navigate` | ✓ | ✓ | ✓ | ✓ |
| `writeContent`, `organizeContent`, `writeTasks`, `writeHandoff` | ✓ | ✓ | ✓ | |
| `manageContext`, `manageAudience`, `archiveContent` | ✓ | ✓ | | |
| `manageWorkspace`, `deleteContent`, `deleteWorkspace` | ✓ | | | |

While a workspace is archived, every capability except `read`, `navigate`, `manageWorkspace`, and `deleteWorkspace` reads `false`.

## Shared errors

| Status | Code | Cause |
| - | - | - |
| `404` | `WORKSPACE_NOT_FOUND` | No workspace with that id (reads also return this when you are not a member) |
| `403` | `WORKSPACE_FORBIDDEN` | You are not a member, or your capabilities lack this operation |
| `409` | `WORKSPACE_ARCHIVED` | A content, context, or handoff write on an archived workspace |

Writes that accept `workspaceSessionId` validate it before writing:

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_WORKSPACE_SESSION` | Not a UUID |
| `403` | `WORKSPACE_SESSION_INVALID` | Not your session, on this API key, in this workspace |
| `409` | `WORKSPACE_SESSION_INACTIVE` / `WORKSPACE_SESSION_EXPIRED` | The session has ended, or expired after 24 hours idle |