Workspace Folders

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. New folder creation needs no revision. Through ordinary folder_create, audience requires explicit workspaceId; standalone team inputs are incompatible with workspace creation and receive WORKSPACE_AUTHORITY before effects.

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
`why`	string	Yes (agents)	One sentence on what the person is trying to accomplish, in their terms (not a description of the edit); required on an agent write to workspace content, at most 300 characters. See Why on every write

Returns the folder (201):

{
  "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`
`why`	string	Yes (agents)	One sentence on what the person is trying to accomplish, in their terms (not a description of the edit); required on an agent write to workspace content, at most 300 characters. See Why on every write

Requires manageAudience. Body { "expectedWorkspaceRevision": n, "why": "<goal>" }. 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):

{ "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 deleting a workspace folder are dashboard-only: PATCH …/folders/{folderId} { slug } and DELETE …/folders/{folderId}?expectedWorkspaceRevision= under /v0/operator/workspaces. Delete needs deleteContent and moves the folder and every artifact in it to the trash for 30 days; reads of those artifacts answer 410 DELETED with via: { type: "folder", id }. Any member with deleteContent can bring the folder back with Restore (type: "folder", the entry’s workspaceRevision), and its artifacts return filed as they were. While a folder is in the trash its slug stays held: 409 FOLDER_EXISTS names the purge date.

Errors

Status	Code	Cause
`400`	`WHY_REQUIRED`	An agent write to workspace content without `why`
`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`
`410`	`WORKSPACE_DELETED`	The workspace is in the trash
`404`	`WORKSPACE_NOT_FOUND`	No workspace with that id

Overview

Identity

Operators

Workspaces

Artifacts

Trash

Table Rows

Versions

Tasks

Activity

Search

Health

Workspace Folders

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

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

Errors

​POST /v0/workspaces/{id}/folders

​PATCH /v0/workspaces/{id}/folders/{folderId}

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

​Errors

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

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

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

Errors