> ## 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.

# Workspace Folders

> /v0/workspaces/:id/folders — Create workspace folders, change their audience, and share their contents

Workspace folders are flat, live inside one workspace (slugs are unique per workspace), and grant nothing by themselves. A `shared` folder shows external members its name and its shared artifacts. An `internal` folder is invisible to them, and its shared artifacts appear at the workspace root. MCP: `folder_create { workspaceId }`, `folder_update`, `folder_share_contents`. CLI: `rip folder create --workspace`, `rip folder update`, `rip folder share-contents`.

List the folders you can see with `GET /v0/folders?workspaceId=<uuid>`. File an artifact into a folder with `PATCH /v0/artifacts/{publicId}` and `{ "folderId": "<uuid>" | null, "expectedWorkspaceRevision": n }`.

**Auth:** `Authorization: Bearer tr_...` (an account API key). `{id}` and `{folderId}` are UUIDs.

## `POST /v0/workspaces/{id}/folders`

Requires `organizeContent`.

| Field | Type | Required | Description |
| - | - | - | - |
| `slug` | string | Yes | 1–64 lowercase letters, digits, or hyphens, starting and ending with a letter or digit |
| `audience` | string | No | `internal` or `shared`. Defaults to `internal` for internal members and `shared` for external editors, who can only create `shared` folders |
| `workspaceSessionId` | string | No | Session attribution |

Returns the folder (201):

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "9d2e…", "slug": "research", "owner_id": "rip1…", "team_id": null,
    "embedding_enabled": null, "artifact_count": 0,
    "created_at": "2026-09-15T08:00:00.000Z", "updated_at": "2026-09-15T08:00:00.000Z",
    "workspace_id": "0b7f…", "audience": "internal", "workspace_revision": 1
  }
}
```

A folder in a team workspace has `team_id` set and `owner_id: null`.

## `PATCH /v0/workspaces/{id}/folders/{folderId}`

Requires `manageAudience`. Returns the folder (`artifact_count` is `null` here).

| Field | Type | Required | Description |
| - | - | - | - |
| `audience` | string | Yes | `internal` or `shared`: the folder's **own** visibility. Its artifacts are unchanged |
| `expectedWorkspaceRevision` | integer | Yes | The folder's current `workspace_revision` |
| `workspaceSessionId` | string | No | Session attribution |

## `POST /v0/workspaces/{id}/folders/{folderId}/share-contents`

Requires `manageAudience`. Body `{ "expectedWorkspaceRevision": n, "workspaceSessionId"?: "<uuid>" }`. Sets the folder **and every artifact currently in it** to `shared` in one transaction (up to 500 artifacts). Artifacts added later are not shared automatically. Returns (201):

```json theme={null}
{ "ok": true, "data": { "folder": { "id": "9d2e…", "audience": "shared", "artifact_count": 3, "…": "…" }, "artifactIds": ["5c9e…", "a13f…", "e802…"] } }
```

`artifactIds` are the public ids of the shared artifacts.

Renaming and removing a workspace folder (removal moves every artifact in it to the root) are dashboard-only: `PATCH …/folders/{folderId} { slug }` and `DELETE …/folders/{folderId}?expectedWorkspaceRevision=` under `/v0/operator/workspaces`.

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_INPUT` | Missing `slug`, or missing/invalid `audience` |
| `400` | `INVALID_SLUG` | The slug does not match the format |
| `400` | `PRECONDITION_REQUIRED` | `expectedWorkspaceRevision` is missing |
| `409` | `CONFLICT` | The folder changed since you read it; the body carries `currentWorkspaceRevision` |
| `400` | `WORKSPACE_BULK_LIMIT` | Share contents: more than 500 artifacts in the folder |
| `409` | `WORKSPACE_CONTENT_CHANGED` | Share contents: the folder's artifacts changed while the request ran; re-read and retry |
| `404` | `FOLDER_NOT_FOUND` | No such folder in this workspace, or it is hidden from you |
| `403` | `WORKSPACE_FORBIDDEN` | Your capabilities lack the operation, or an external editor asked for `internal` |
| `409` | `WORKSPACE_ARCHIVED` | The workspace is archived |
| `404` | `WORKSPACE_NOT_FOUND` | No workspace with that id |

A `workspaceSessionId` is validated as described in [Shared errors](/api-reference/workspaces/overview#shared-errors).