{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):
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.