# Riverside API

> Every Riverside endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/riverside

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

12 endpoints for Riverside. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/riverside`
- Connects with: Your own Riverside account (host, account owner, admin, director or editor, depending on the call)
- Integration page: https://cotlet.dev/integrations/riverside-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `list_studios` | read | Your studios with name, recording type and the studio link. |
| `list_sessions` | read | Sessions from the studio Planner, with time, time zone and invited people. |
| `get_invite_links` | read | The studio links to share with a guest, a producer or an audience. |
| `list_recordings` | read | Recordings in your projects, newest first, with duration, participants and upload status. |
| `get_recording` | read | One recording with its date, duration and each participant's tracks, with type and upload status. |
| `get_transcript` | read | The transcript of a recording with speaker names and timestamps. |
| `download_tracks` | read | Download links for the separate track of each participant in a recording. |
| `create_studio` | write | Create a new studio for a show. |
| `schedule_session` | write | Add a session to the studio Planner and email the people you invite. |
| `update_session` | write | Rename or reschedule a session, or change who is invited. |
| `invite_guest` | write | Email a studio invite for a scheduled session to a guest, producer or audience member. |
| `cancel_session` | write | Remove a scheduled session from the Planner. Recordings already made are kept. |

## List studios

`POST https://cotlet.dev/api/v1/riverside/list_studios`

Access: read.

Returns every studio in your account, the ones you own and the ones you were added to. Use studio_id from each item in the other calls. Recording type is audio and video or audio only, as set in the studio.

### Parameters

No parameters.

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/list_studios \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("riverside", "list_studios")
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'list_studios');
```

**CLI**

```bash
cotlet call riverside list_studios
```

### Example response

```json
{
  "studios": [
    {
      "studio_id": "std_8f2k41",
      "name": "The Product Hour",
      "recording_type": "audio_video",
      "studio_url": "https://riverside.com/studio/the-product-hour"
    },
    {
      "studio_id": "std_2m9c07",
      "name": "Founders Q&A",
      "recording_type": "audio_only",
      "studio_url": "https://riverside.com/studio/founders-qa"
    }
  ]
}
```

## List sessions

`POST https://cotlet.dev/api/v1/riverside/list_sessions`

Access: read.

Lists scheduled sessions in start order, soonest first. Each item has the invited guests, producers and audience members with their roles. Pass session_id to update_session, invite_guest or cancel_session.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `studio_id` | string | no | Only this studio. Default: all studios. |
| `from` | date | no | Sessions on or after this date. Default: today. |
| `to` | date | no | Sessions on or before this date. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/list_sessions \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("riverside", "list_sessions")
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'list_sessions');
```

**CLI**

```bash
cotlet call riverside list_sessions
```

### Example response

```json
{
  "sessions": [
    {
      "session_id": "ses_3vq9x7",
      "studio_id": "std_8f2k41",
      "name": "Episode 42: Pricing your first product",
      "start": "2026-10-15T15:00:00+01:00",
      "end": "2026-10-15T16:00:00+01:00",
      "invited": [
        {
          "email": "guest@example.com",
          "role": "guest"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

## Get invite links

`POST https://cotlet.dev/api/v1/riverside/get_invite_links`

Access: read.

Returns the studio link for each role. Guest and producer links let people join the studio; the audience link works only while audience public access is turned on in the studio. A link you share yourself does not expire, unlike the link in an invite email.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `studio_id` | string | yes | Studio ID from list_studios. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/get_invite_links \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"studio_id":"studio_8c41d2"}'
```

**Python**

```python
result = client.call("riverside", "get_invite_links", {"studio_id":"studio_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'get_invite_links', {"studio_id":"studio_8c41d2"});
```

**CLI**

```bash
cotlet call riverside get_invite_links --data '{"studio_id":"studio_8c41d2"}'
```

### Example response

```json
{
  "studio_id": "std_8f2k41",
  "links": {
    "guest": "https://riverside.com/studio/the-product-hour?t=guest-token",
    "producer": "https://riverside.com/studio/the-product-hour?t=producer-token",
    "audience": null
  }
}
```

## List recordings

`POST https://cotlet.dev/api/v1/riverside/list_recordings`

Access: read.

Lists recordings across your studios, newest first. Filter by studio or by date to find the latest episode. Upload status shows whether each participant's files are fully uploaded. Pass recording_id to get_recording, get_transcript and download_tracks.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `studio_id` | string | no | Only this studio. Default: all studios. |
| `since` | date | no | Only recordings made on or after this date. |
| `limit` | integer | no | 1 to 50. Default: 20. |
| `cursor` | string | no | Next page cursor from the previous call. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/list_recordings \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("riverside", "list_recordings")
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'list_recordings');
```

**CLI**

```bash
cotlet call riverside list_recordings
```

### Example response

```json
{
  "recordings": [
    {
      "recording_id": "rec_71d3ab",
      "studio_id": "std_8f2k41",
      "title": "Episode 41: Launch week",
      "recorded_at": "2026-10-08T15:02:00+01:00",
      "duration_seconds": 3412,
      "participants": [
        "Host",
        "Guest"
      ],
      "upload_status": "complete"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjIwfQ"
}
```

## Get recording

`POST https://cotlet.dev/api/v1/riverside/get_recording`

Access: read.

Returns one recording and the tracks of each participant. Each track has a type (audio or video, and screen share when one was recorded) and an upload status. Read it before download_tracks to see whether every track has finished uploading.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `recording_id` | string | yes | Recording ID from list_recordings. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/get_recording \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recording_id":"recording_8c41d2"}'
```

**Python**

```python
result = client.call("riverside", "get_recording", {"recording_id":"recording_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'get_recording', {"recording_id":"recording_8c41d2"});
```

**CLI**

```bash
cotlet call riverside get_recording --data '{"recording_id":"recording_8c41d2"}'
```

### Example response

```json
{
  "recording_id": "rec_71d3ab",
  "title": "Episode 41: Launch week",
  "duration_seconds": 3412,
  "participants": [
    {
      "name": "Host",
      "tracks": [
        {
          "type": "audio",
          "upload_status": "complete"
        },
        {
          "type": "video",
          "upload_status": "complete"
        }
      ]
    },
    {
      "name": "Guest",
      "tracks": [
        {
          "type": "audio",
          "upload_status": "complete"
        },
        {
          "type": "video",
          "upload_status": "uploading"
        }
      ]
    }
  ]
}
```

## Get transcript

`POST https://cotlet.dev/api/v1/riverside/get_transcript`

Access: read.

Returns the transcript Riverside made for one recording, in speaker order with timestamps. Use format srt for subtitle files and txt for plain reading. The call fails if the recording has no transcript yet.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `recording_id` | string | yes | Recording ID from list_recordings. |
| `format` | enum | no | txt or srt. Default: txt. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/get_transcript \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recording_id":"recording_8c41d2"}'
```

**Python**

```python
result = client.call("riverside", "get_transcript", {"recording_id":"recording_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'get_transcript', {"recording_id":"recording_8c41d2"});
```

**CLI**

```bash
cotlet call riverside get_transcript --data '{"recording_id":"recording_8c41d2"}'
```

### Example response

```json
{
  "recording_id": "rec_71d3ab",
  "format": "txt",
  "text": "[00:00:04] Host: Welcome back to The Product Hour.\n[00:00:09] Guest: Thanks for having me."
}
```

## Download tracks

`POST https://cotlet.dev/api/v1/riverside/download_tracks`

Access: read.

Returns one download link per participant for the file type you choose: raw video, aligned video, raw audio or compressed audio, the options in the Riverside Download menu. Tracks that are still uploading are listed without a link. Screen share tracks in high quality exist only when the screen share was recorded with the Mac app. Edited tracks are not included; they come from an edit export.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `recording_id` | string | yes | Recording ID from list_recordings. |
| `file_type` | enum | no | raw_video, aligned_video, raw_audio or compressed_audio, as named in the Riverside Download menu. Default: raw_audio. |
| `participants` | string[] | no | Only these participant names. Default: everyone. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/download_tracks \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recording_id":"rec_71d3ab","file_type":"raw_audio"}'
```

**Python**

```python
result = client.call("riverside", "download_tracks", {"recording_id":"rec_71d3ab","file_type":"raw_audio"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'download_tracks', {"recording_id":"rec_71d3ab","file_type":"raw_audio"});
```

**CLI**

```bash
cotlet call riverside download_tracks --data '{"recording_id":"rec_71d3ab","file_type":"raw_audio"}'
```

### Example response

```json
{
  "recording_id": "rec_71d3ab",
  "file_type": "raw_audio",
  "files": [
    {
      "participant": "Host",
      "url": "https://downloads.example.com/rec_71d3ab/host.wav",
      "status": "ready"
    },
    {
      "participant": "Guest",
      "url": "https://downloads.example.com/rec_71d3ab/guest.wav",
      "status": "ready"
    }
  ]
}
```

## Create studio

`POST https://cotlet.dev/api/v1/riverside/create_studio`

Access: write. Confirm: waits for the user's OK before it runs.

Creates a studio with the name and recording type you give. Studios count against the limit of your Riverside plan, so a new one can use up a slot. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Studio name, for example the show title. |
| `recording_type` | enum | no | audio_video or audio_only. Default: audio_video. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/create_studio \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe"}'
```

**Python**

```python
result = client.call("riverside", "create_studio", {"name":"Jane Doe"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'create_studio', {"name":"Jane Doe"});
```

**CLI**

```bash
cotlet call riverside create_studio --data '{"name":"Jane Doe"}'
```

### Example response

```json
{
  "studio_id": "std_5t8n22",
  "name": "Interview Series",
  "recording_type": "audio_video",
  "studio_url": "https://riverside.com/studio/interview-series"
}
```

## Schedule session

`POST https://cotlet.dev/api/v1/riverside/schedule_session`

Access: write. Confirm: waits for the user's OK before it runs.

Adds a session at the start and end time you give, in the time zone you set. Each guest in guest_emails gets an invite email with the session details and the studio link; the emailed link works until 24 hours after the start. Only the host, account owner, admins, directors and editors can schedule. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `studio_id` | string | yes | Studio ID from list_studios. |
| `name` | string | yes | Session name, for example the episode title. |
| `start` | datetime | yes | ISO 8601 with time zone. |
| `end` | datetime | yes | ISO 8601 with time zone. |
| `guest_emails` | string[] | no | Guests to invite now. Default: none. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/schedule_session \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"studio_id":"std_8f2k41","name":"Episode 42: Pricing your first product","start":"2026-10-15T15:00:00+01:00","end":"2026-10-15T16:00:00+01:00","guest_emails":["guest@example.com"]}'
```

**Python**

```python
result = client.call("riverside", "schedule_session", {"studio_id":"std_8f2k41","name":"Episode 42: Pricing your first product","start":"2026-10-15T15:00:00+01:00","end":"2026-10-15T16:00:00+01:00","guest_emails":["guest@example.com"]})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'schedule_session', {"studio_id":"std_8f2k41","name":"Episode 42: Pricing your first product","start":"2026-10-15T15:00:00+01:00","end":"2026-10-15T16:00:00+01:00","guest_emails":["guest@example.com"]});
```

**CLI**

```bash
cotlet call riverside schedule_session --data '{"studio_id":"std_8f2k41","name":"Episode 42: Pricing your first product","start":"2026-10-15T15:00:00+01:00","end":"2026-10-15T16:00:00+01:00","guest_emails":["guest@example.com"]}'
```

### Example response

```json
{
  "session_id": "ses_3vq9x7",
  "studio_id": "std_8f2k41",
  "status": "scheduled",
  "start": "2026-10-15T15:00:00+01:00",
  "invited": [
    {
      "email": "guest@example.com",
      "role": "guest",
      "email_sent": true
    }
  ]
}
```

## Update session

`POST https://cotlet.dev/api/v1/riverside/update_session`

Access: write. Confirm: waits for the user's OK before it runs.

Changes the fields you pass and leaves the rest. When the date or time changes, Riverside emails the guests, producer and audience members that the session was updated, and the Google Calendar invite updates automatically. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID from list_sessions. |
| `name` | string | no | New session name. |
| `start` | datetime | no | New start, ISO 8601 with time zone. |
| `end` | datetime | no | New end, ISO 8601 with time zone. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/update_session \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"ses_3vq9x7","start":"2026-10-16T11:00:00+01:00","end":"2026-10-16T12:00:00+01:00"}'
```

**Python**

```python
result = client.call("riverside", "update_session", {"session_id":"ses_3vq9x7","start":"2026-10-16T11:00:00+01:00","end":"2026-10-16T12:00:00+01:00"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'update_session', {"session_id":"ses_3vq9x7","start":"2026-10-16T11:00:00+01:00","end":"2026-10-16T12:00:00+01:00"});
```

**CLI**

```bash
cotlet call riverside update_session --data '{"session_id":"ses_3vq9x7","start":"2026-10-16T11:00:00+01:00","end":"2026-10-16T12:00:00+01:00"}'
```

### Example response

```json
{
  "session_id": "ses_3vq9x7",
  "status": "updated",
  "start": "2026-10-16T11:00:00+01:00",
  "end": "2026-10-16T12:00:00+01:00",
  "notified": [
    "guest@example.com"
  ]
}
```

## Invite guest

`POST https://cotlet.dev/api/v1/riverside/invite_guest`

Access: write. Confirm: waits for the user's OK before it runs.

Adds one person to a scheduled session and sends them an invite email with the session details and the studio link. Role is guest by default. Inviting the same email again resends the invite. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID from list_sessions. |
| `email` | string | yes | Who to invite. |
| `role` | enum | no | guest, producer or audience. Default: guest. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/invite_guest \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session_8c41d2","email":"jane@example.com"}'
```

**Python**

```python
result = client.call("riverside", "invite_guest", {"session_id":"session_8c41d2","email":"jane@example.com"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'invite_guest', {"session_id":"session_8c41d2","email":"jane@example.com"});
```

**CLI**

```bash
cotlet call riverside invite_guest --data '{"session_id":"session_8c41d2","email":"jane@example.com"}'
```

### Example response

```json
{
  "session_id": "ses_3vq9x7",
  "email": "producer@example.com",
  "role": "producer",
  "email_sent": true
}
```

## Cancel session

`POST https://cotlet.dev/api/v1/riverside/cancel_session`

Access: write. Confirm: waits for the user's OK before it runs.

Cancels the session and removes it from the Planner and the project folder. Recordings that were already made stay in your account. Cancelling cannot be undone with one call; schedule the session again to restore it. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `session_id` | string | yes | Session ID from list_sessions. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/riverside/cancel_session \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"session_8c41d2"}'
```

**Python**

```python
result = client.call("riverside", "cancel_session", {"session_id":"session_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('riverside', 'cancel_session', {"session_id":"session_8c41d2"});
```

**CLI**

```bash
cotlet call riverside cancel_session --data '{"session_id":"session_8c41d2"}'
```

### Example response

```json
{
  "session_id": "ses_3vq9x7",
  "status": "cancelled"
}
```