# Create a folder

`POST /folder.create`

## Description

Create a folder for meetings and Magicasts. The new folder is visible only
to its members: file items with [`folder.addContents`](/docs/api/folder-add-contents)
and share it with [`folder.addMembers`](/docs/api/folder-add-members).

**Access:** Organization and Personal. With a personal token, the token's
owner becomes the folder's `admin`; `ownerId` is not accepted. With an
organization token, `ownerId` is required and names the person in the
account who becomes the `admin`. Account admins get no implicit access to
folders in Roam, so a folder must start with a person who can see it.

**Required scope:** `folders:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | Yes | Folder name. Leading and trailing whitespace is trimmed. |
| `ownerId` | string | No | User ID of the person who becomes the folder's `admin`. Required for Organization access; rejected for Personal access.  |

## Responses

### 200 - Folder created

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ok` | "true" | Yes | Always `true` on success. See [Responses and Errors](/docs/guides/responses-and-errors). |
| `folder` | Folder | Yes |  |

**Folder**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Folder ID. |
| `name` | string | Yes | Folder name. |
| `itemCount` | integer | Yes | Number of meetings and Magicasts filed in the folder. |
| `createdAt` | string | Yes | When the folder was created (RFC-3339). |
| `role` | "admin" | "viewer" | No | The caller's role. Present for Personal access only: `admin` is the folder owner, `viewer` can read. Omitted for Organization access.  |


#### Example Response

```json
{
  "ok": true,
  "folder": {
    "id": "019a0000-0000-7000-8000-0000000000f1",
    "name": "Customer calls",
    "itemCount": 0,
    "createdAt": "2026-01-21T18:30:00Z",
    "role": "admin"
  }
}
```

### 400 - Bad request. Common causes:
- Missing or empty `name` (`missing_parameter`)
- `name` longer than 255 characters
- Missing `ownerId` with an organization token (`missing_parameter`), or `ownerId` sent with a personal token (`invalid_parameter`)
- Malformed JSON body or an unknown field (`invalid_json`)


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Token is missing `folders:write` (`missing_scope`)


### 404 - Not found. Common causes:
- `ownerId` is not a person in the account (`user_not_found`)


### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/folder-create*