# List folders

`GET /folder.list`

## Description

List folders of meetings and Magicasts, newest first.

**Access:** Organization and Personal. Personal tokens return only folders
the token owner belongs to, each with that person's `role` (`admin` or
`viewer`). Organization tokens return every folder in the account, and
`role` is omitted.

**Required scope:** `folders:read`

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `after` | query | string | No | Only return folders created after this time (RFC-3339 or `YYYY-MM-DD`). Results switch to oldest-first. Sub-millisecond precision is truncated.  |
| `before` | query | string | No | Only return folders created before this time (RFC-3339 or `YYYY-MM-DD`). Sub-millisecond precision is truncated.  |
| `limit` | query | integer | No | Number of folders to return per page. Default 10, maximum 100. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Folders retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ok` | "true" | Yes | Always `true` on success. See [Responses and Errors](/docs/guides/responses-and-errors). |
| `folders` | Folder[] | No |  |
| `nextCursor` | string | No | Cursor for the next page. Omitted on the last page. |

**Folder** (array item):

| 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,
  "folders": [
    {
      "id": "019a0000-0000-7000-8000-0000000000f1",
      "name": "Sales",
      "itemCount": 2,
      "createdAt": "2026-01-21T18:30:00Z",
      "role": "admin"
    },
    {
      "id": "019a0000-0000-7000-8000-0000000000f2",
      "name": "Design reviews",
      "itemCount": 5,
      "createdAt": "2026-01-14T15:00:00Z",
      "role": "viewer"
    }
  ],
  "nextCursor": "YzE6MjAyNi0wMS0xNFQxNTowMDowMFo6MDE5YTAwMDA"
}
```

### 400 - Bad request. Invalid `after`, `before`, `limit`, or `cursor`.

### 401 - Presented invalid authentication credentials.

### 403 - Token is missing `folders:read`.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

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