# List folder contents

`GET /folder.contents`

## Description

List the meetings and Magicasts filed in a folder, newest first, with
each item's metadata.

Reading the folder is what grants access to these rows. A meeting or
Magicast is included even when the caller would not see it on
[`meeting.list`](/docs/api/meeting-list) or
[`magicast.list`](/docs/api/magicast-list). If the item was deleted after
it was filed, `type`, `id`, and `addedAt` are still returned and the
embedded `meeting` or `magicast` object is omitted.

A personal token that can read the folder can then call
[`meeting.info`](/docs/api/meeting-info),
[`meeting.transcript`](/docs/api/meeting-transcript), and
[`meeting.prompt`](/docs/api/meeting-prompt) for a filed meeting, and
[`magicast.info`](/docs/api/magicast-info) for a filed Magicast. Those
calls need `meetings:read` or `magicast:read` in addition to
`folders:read`. [`magicast.shareLink`](/docs/api/magicast-share-link)
stays limited to the Magicast owner. Organization follow-ups on meetings
still follow [Meeting width](/docs/guides/scopes#meeting-width-adminmeetingsread).

**Access:** Organization and Personal. Same visibility as
[`folder.info`](/docs/api/folder-info): a folder the caller cannot see
returns `404` `folder_not_found`.

**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 |
|------|-----|------|----------|-------------|
| `id` | query | string | Yes | Folder ID. |
| `type` | query | "meeting" | "magicast" | No | Only return this kind of item. Omit to return both. |
| `after` | query | string | No | Only return items filed 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 items filed before this time (RFC-3339 or `YYYY-MM-DD`). Sub-millisecond precision is truncated.  |
| `limit` | query | integer | No | Number of items 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 - Folder contents retrieved successfully

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

**FolderContent** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | "meeting" | "magicast" | Yes | Kind of item. |
| `id` | string | Yes | Meeting ID or Magicast ID. |
| `addedAt` | string | Yes | When the item was filed in the folder (RFC-3339). |
| `meeting` | object | No | Present when `type` is `meeting` and the meeting could be loaded. |
| `magicast` | object | No | Present when `type` is `magicast` and the Magicast could be loaded. |


#### Example Response

```json
{
  "ok": true,
  "contents": [
    {
      "type": "meeting",
      "id": "019a0000-0000-7000-8000-0000000000e1",
      "addedAt": "2026-02-02T16:00:00Z",
      "meeting": {
        "id": "019a0000-0000-7000-8000-0000000000e1",
        "title": "Quarterly review",
        "start": "2026-02-02T15:00:00Z",
        "end": "2026-02-02T15:45:00Z",
        "participantCount": 3,
        "hasVideo": true,
        "videoStatus": "available"
      }
    },
    {
      "type": "magicast",
      "id": "019a0000-0000-7000-8000-0000000000c1",
      "addedAt": "2026-01-28T12:00:00Z",
      "magicast": {
        "id": "019a0000-0000-7000-8000-0000000000c1",
        "name": "Demo",
        "createdAt": "2026-01-28T11:30:00Z",
        "ownerId": "709b8a57-70bc-427a-b6f0-b16ba5297f8c"
      }
    }
  ],
  "nextCursor": "YzE6MjAyNi0wMS0yOFQxMjowMDowMFo6MDE5YTAwMDA"
}
```

### 400 - Bad request. Missing or invalid `id`, `type`, date, `limit`, or `cursor`.

### 401 - Presented invalid authentication credentials.

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

### 404 - Folder not found, or not visible to the caller (`folder_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-contents*