# Recordings

## List recordings

```
GET /api/v1/recordings
```

Returns a paginated list of recordings accessible to the authenticated user.

### Query parameters

| Parameter         | Type   | Default | Description                                                      |
| ----------------- | ------ | ------- | ---------------------------------------------------------------- |
| `limit`           | number | `20`    | Number of results (1–100)                                        |
| `offset`          | number | `0`     | Pagination offset                                                |
| `search`          | string | —       | Filter by title (partial match)                                  |
| `status`          | string | —       | Filter by status (see [Recording statuses](#recording-statuses)) |
| `date_from`       | string | —       | ISO 8601 date — only return recordings created on or after       |
| `date_to`         | string | —       | ISO 8601 date — only return recordings created on or before      |
| `organization_id` | string | —       | Scope to an organization                                         |
| `folder_id`       | string | —       | Scope to a folder (requires `organization_id`)                   |

### Response

```json
{
  "data": [
    {
      "id": "uuid",
      "status": "COMPLETED",
      "title": "Weekly sync",
      "createdAt": "2025-09-19T15:00:00.000Z",
      "thumbnailUrl": "https://...",
      "progress": 1.0,
      "capabilities": {
        "canDownload": true,
        "canShare": true,
        "canViewTranscription": true,
        "canGenerateSummary": true,
        "canAskQuestions": true
      }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

***

## Get recording

```
GET /api/v1/recordings/:id
```

Returns full details for a single recording.

### Response

```json
{
  "data": {
    "id": "uuid",
    "status": "COMPLETED",
    "title": "Weekly sync",
    "createdAt": "2025-09-19T15:00:00.000Z",
    "updatedAt": "2025-09-19T15:30:00.000Z",
    "startedAt": "2025-09-19T15:01:00.000Z",
    "endedAt": "2025-09-19T15:30:00.000Z",
    "videoUrl": "https://...",
    "hlsUrl": "https://...",
    "downloadUrl": "https://...",
    "downloadUrlExpiresAt": "2025-09-19T21:00:00.000Z",
    "thumbnailUrl": "https://...",
    "organizationId": "org_uuid or null",
    "transcription": {
      "status": "completed",
      "language": "en",
      "speakers": ["Speaker 1", "Speaker 2"],
      "segmentsCount": 184,
      "duration": 1740.5
    },
    "summary": {
      "status": "completed",
      "content": "## Key topics\n...",
      "topics": [
        {
          "title": "Project timeline",
          "keyPoints": [
            { "point": "Launch date confirmed", "details": ["Set for Q1"] }
          ]
        }
      ]
    },
    "isLocked": false,
    "capabilities": {
      "canDownload": true,
      "canShare": true,
      "canViewTranscription": true,
      "canStartTranscription": true,
      "canRegenerateTranscription": false,
      "canRenameSpeaker": true,
      "canViewSummary": true,
      "canGenerateSummary": true,
      "canAskQuestions": true
    }
  }
}
```

***

## Get transcript segments

```
GET /api/v1/recordings/:id/transcript
```

Returns paginated transcript segments for a recording.

### Query parameters

| Parameter     | Type   | Default | Description               |
| ------------- | ------ | ------- | ------------------------- |
| `start_chunk` | number | `0`     | Chunk index to start from |
| `limit`       | number | `50`    | Number of chunks (1–100)  |

### Response

```json
{
  "data": {
    "status": "completed",
    "language": "en",
    "speakers": ["Speaker 1", "Alice"],
    "duration": 1740.5,
    "segments": [
      {
        "id": 1,
        "start": 0.5,
        "end": 3.2,
        "text": "Good morning everyone.",
        "speaker": "Alice",
        "confidence": 0.97
      }
    ],
    "pagination": {
      "total_chunks": 184,
      "has_more": true
    }
  }
}
```

***

## Update recording

```
PATCH /api/v1/recordings/:id
```

Update the title or notes of a recording. At least one field is required.

### Request body

```json
{
  "title": "New title (1–500 characters)",
  "notes": "Optional notes (max 100,000 characters)"
}
```

### Response

```json
{
  "data": { "success": true }
}
```

***

## Delete recording

```
DELETE /api/v1/recordings/:id
```

Permanently deletes a recording and all associated data (transcript, summary, shares).

### Response

```json
{
  "data": { "success": true }
}
```

{% hint style="danger" %}
Deletion is permanent and cannot be undone.
{% endhint %}

***

## Create share link

```
POST /api/v1/recordings/:id/share-link
```

Generates a public share link for the recording.

### Request body

```json
{
  "permission": "view"
}
```

| Value      | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `view`     | Recipients can watch the video and access the transcript/summary |
| `download` | Recipients can also download the video file                      |

### Response

```json
{
  "data": {
    "share_url": "https://recordmeeting.com/app/shared/abc123",
    "share_token": "abc123",
    "permission": "view"
  }
}
```

***

## Recording statuses

| Status          | Description                                   |
| --------------- | --------------------------------------------- |
| `STARTING`      | Recording request received, setup in progress |
| `CONNECTING`    | Connecting to the Google Meet session         |
| `WAIT_APPROVAL` | Waiting for in-call approval to record        |
| `RECORDING`     | Actively recording                            |
| `PROCESSING`    | Post-recording composition and processing     |
| `TRANSCODING`   | Transcoding video for streaming               |
| `UPLOADING`     | Uploading to storage                          |
| `COMPLETED`     | Recording ready to view                       |
| `ERROR`         | Recording failed                              |