Beta

Create Room folders

Last updated Nov 19, 2026View as MarkdownAgent setup / MCP
POST
/v1/rooms/{room_id}/folders

Makes Room folders. Send them all in one call as folders (1 to 100, in order, all or nothing); name alone makes one. Each goes at the top, inside an existing folder (parent_folder_id), or inside one made earlier in the call (give that one a ref, then parent_ref). Needs Can edit there, and follows who can see where it goes. Returns count and folders (room_folder_id, name, position) in order; a refused folder is details.folder_index.

Authorization

headerAuthorizationBearer <token>

A signed-in SMB user's access token. Workspace-scoped operations also require SMB-Workspace-Id.

Path Parameters

room_id*string
Match^rom_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Header Parameters

SMB-Workspace-Id*string

Workspace where this operation runs. Required for user tokens and Workspace API keys.

Formatuuid
Idempotency-Key*string
Length8 <= length <= 200

Request Body

application/json
  1. body
name*string
Match^[^\u0000-\u001f\u007f]+$
Length1 <= length <= 200
parent_folder_id?|null
folders?array<>
Items1 <= items <= 100

Response Body

The existing resource or idempotent replay was returned.

application/json
  1. response
room_folder_id*string
Match^rfd_[0-7][0-9A-HJKMNP-TV-Z]{25}$
room_id*string
Match^rom_[0-7][0-9A-HJKMNP-TV-Z]{25}$
parent_folder_id*|

The folder it is in; null at the top (or when you can't open the folder above).

name*string
position*integer
Range-9007199254740991 <= value <= 9007199254740991
access_mode*AccessMode

inherit: everyone who can see the folder above (or the Room). restricted: only people added to it.

Value in"inherit""restricted"
item_count*ItemCount

Folders and files inside it that you can see.

Range-9007199254740991 <= value <= 9007199254740991
access_level*string

Your access on this folder.

Value in"view""edit""full_access"
created_at*string
updated_at*string
request_id*string
curl -X POST 'https://example.com/v1/rooms/string/folders' \  -H 'SMB-Workspace-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Idempotency-Key: stringst' \  -H 'Content-Type: application/json' \  -d '{}'
{  "room_folder_id": "string",  "room_id": "string",  "parent_folder_id": "string",  "name": "string",  "position": -9007199254740991,  "access_mode": "inherit",  "item_count": -9007199254740991,  "access_level": "view",  "created_at": "string",  "updated_at": "string",  "request_id": "string"}