Skip to main content
Folders are flat named buckets for artifacts and grant nothing by themselves. One set of routes serves every kind: personal, team, and workspace folders. A workspace folder lives inside one workspace (slugs are unique per workspace). Everyone in the workspace sees every folder in it. Naming a folder. {folder} is the folder’s id, which names one folder of any kind on its own, or its slug. A slug is looked up in workspaceId when you send one, else in team (a slug or id, members only), else among your personal folders. A folder you cannot reach answers 404 FOLDER_NOT_FOUND, exactly as an id that names nothing. A folder whose workspace is in the trash answers that workspace’s members 410 WORKSPACE_DELETED. team beside a folder id, or team with workspaceId, is 400 INVALID_FIELD. On GET the scope goes in the query; on every other method it goes in the JSON body. MCP: folder_create and folder_list take the scope; folder_show, folder_update (rename or history) and folder_delete take the folder as id, plus the same scope for a slug. CLI: rip folder create|list|show|rename|update|delete with --team or --workspace-id. File an artifact into a folder with PATCH /v0/artifacts/{artifactId} and { "folder": "<folder id or slug>" | null } (a slug resolves in the artifact’s workspace; null unfiles), or create it there with folder on Create Artifact. Auth: Authorization: Bearer tr_... (an account API key).

POST /v0/folders

Creates a personal folder, a team’s (team), or a workspace’s (workspaceId). A workspace folder needs organizeContent and, from an agent, why; it needs no revision. Returns the folder (201):
A team folder, and a folder in a team workspace, has team_id set and owner_id: null. Only a workspace folder carries workspace_id and workspace_revision. A create 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.”

GET /v0/folders

Your personal folders, a team’s (?team=), or a workspace’s (?workspaceId=), each with its live artifact_count.

GET /v0/folders/{folder}

One folder. artifact_count counts a personal or team folder’s live files; it is null for a workspace folder. A folder in the trash answers 410 DELETED.

PATCH /v0/folders/{folder}

Rename a folder of any kind (newSlug) or set any folder’s history (history): one per call. Returns the folder.

DELETE /v0/folders/{folder}

Moves the folder and every artifact in it to the trash for 30 days. Inputs go in the JSON body: { "team"?, "workspaceId"?, "expectedWorkspaceRevision"?, "why"? }. Personal: the owner; team: any member; workspace: deleteContent, with why from an agent. Reads of those artifacts answer 410 DELETED with via: { type: "folder", id }. Bring the folder back with Restore, 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. Repeating the delete returns the same dates.

Errors