# Create Room folders (/docs/api-reference/create_room_folder)

`POST /v1/rooms/{room_id}/folders` · operation `create_room_folder`

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.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `room_id` | string | yes |  |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `SMB-Workspace-Id` | string (uuid) | yes | Workspace where this operation runs. Required for user tokens and Workspace API keys. |
| `Idempotency-Key` | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `parent_folder_id` | string or null | no |  |
| `folders` | array of object | no |  |
| `folders[].name` | string | yes |  |
| `folders[].parent_folder_id` | string or null | no |  |
| `folders[].ref` | string | no | A name for this folder, for parent_ref. |
| `folders[].parent_ref` | string | no | The ref of a folder earlier in folders. |

Send exactly one of these shapes:

1. Send `name`.
2. Send `folders`.

### Response

**200** The existing resource or idempotent replay was returned. · **201** The resource was created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `room_folder_id` | string | yes |  |
| `room_id` | string | yes |  |
| `parent_folder_id` | string or null | yes | The folder it is in; null at the top (or when you can't open the folder above). |
| `name` | string | yes |  |
| `position` | integer | yes |  |
| `access_mode` | one of `inherit`, `restricted` | yes | inherit: everyone who can see the folder above (or the Room). restricted: only people added to it. |
| `item_count` | integer | yes | Folders and files inside it that you can see. |
| `access_level` | one of `view`, `edit`, `full_access` | yes | Your access on this folder. |
| `created_at` | string | yes |  |
| `updated_at` | string | yes |  |
| `request_id` | string | yes |  |
| `count` | integer | yes |  |
| `folders` | array of object | yes | In the order sent. |
| `folders[].room_folder_id` | string | yes |  |
| `folders[].name` | string | yes |  |
| `folders[].position` | integer | yes |  |
| `folders[].ref` | string | no |  |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request POST "https://api.smb.co/v1/rooms/$ROOM_ID/folders" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"…"}'
```