---
sidebar_position: 7
title: Recordings & Transcriptions
description: List, stream, download and delete call recordings and transcriptions with presigned S3 URLs — build zero-retention workflows with the Workspace API.
---

# Recordings & Transcriptions

Manage call recordings and AI transcriptions stored in your workspace. Use these endpoints to fetch playable media, archive files to your own storage, and **permanently delete** recordings or transcriptions according to your company's data retention policy.

All endpoints require `ApiKey` authentication:

```
Authorization: ApiKey sk-YOUR_API_KEY
```

| Method   | Endpoint                                          | Description                                                     |
| -------- | ------------------------------------------------- | --------------------------------------------------------------- |
| `GET`    | `/calls/:id/recordings`                           | List all recordings of a call with presigned stream/download URLs |
| `GET`    | `/calls/:id/recordings/stream`                    | Stream the primary (first) recording of a call                  |
| `GET`    | `/calls/:id/recordings/:index/stream`             | Stream a recording by index                                     |
| `GET`    | `/calls/:id/recordings/:index/download`           | Download a recording file (`302` redirect or JSON)              |
| `DELETE` | `/calls/:id/recordings`                           | Delete all recordings of a call                                 |
| `DELETE` | `/calls/:id/recordings/:recording_id`             | Delete a single recording                                       |
| `GET`    | `/recordings`                                     | List all recordings in the workspace (paginated, filterable)    |
| `DELETE` | `/recordings/bulk`                                | Bulk delete up to 100 recordings by ID                          |
| `GET`    | `/calls/:id/transcription`                        | Get the transcription of a call                                 |
| `DELETE` | `/calls/:id/transcription`                        | Delete the transcription of a call                              |
| `GET`    | `/transcriptions`                                 | List all transcriptions in the workspace (paginated, filterable) |
| `DELETE` | `/transcriptions/bulk`                            | Bulk delete up to 100 transcriptions by ID                      |

:::info Presigned URLs
Recording files are stored privately on S3. The `stream_url`, `download_url` and the `url` delivered in the [`call.recording.ready`](/developers/webhooks/event-catalog#callrecordingready) webhook are **presigned, time-limited URLs** — they cannot be accessed publicly and expire **2 hours** after they are issued.

Download the file as soon as you receive the webhook. If a URL has expired, call `GET /calls/:id/recordings` to obtain fresh URLs.
:::

---

## List Recordings of a Call

```
GET /calls/:id/recordings
```

### Example Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/calls/call_01h900000000000000000001/recordings" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

### Response `200 OK`

```json
{
  "call_id": "call_01h900000000000000000001",
  "recordings": [
    {
      "index": 0,
      "id": "rec_01h900000000000000000001",
      "start_time": "2026-08-17T11:01:11.035Z",
      "end_time": "2026-08-17T11:01:27.163Z",
      "duration": 16,
      "format": "wav",
      "size_bytes": 256000,
      "file": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav",
      "stream_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?X-Amz-Signature=...",
      "download_url": "https://firetell-asia-south1.s3.amazonaws.com/yourcompany/recordings/call_01h.../rec.wav?response-content-disposition=attachment..."
    }
  ]
}
```

---

## Download a Recording

```
GET /calls/:id/recordings/:index/download
```

| Query Parameter | Type    | Default | Description                                                                 |
| --------------- | ------- | ------- | --------------------------------------------------------------------------- |
| `redirect`      | boolean | `true`  | When `true`, responds `302` to the presigned download URL. When `false`, returns JSON metadata. |

```bash
curl -L -o recording.wav \
  "https://{workspace_id}.firetell.app/api/v1/calls/call_01h900000000000000000001/recordings/0/download" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

---

## Delete Recordings

Deletion is **permanent**: audio files are removed from cloud storage and cannot be recovered. Call metadata (CDR: time, duration, cost, status) is preserved for billing and audit purposes.

### Delete a single recording

```
DELETE /calls/:id/recordings/:recording_id
```

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/calls/call_01h900000000000000000001/recordings/rec_01h900000000000000000001" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"
```

```json
{
  "message": "Recording deleted successfully",
  "call_id": "call_01h900000000000000000001",
  "recording_id": "rec_01h900000000000000000001",
  "freed_bytes": 256000,
  "remaining_recordings": 0
}
```

### Delete all recordings of a call

```
DELETE /calls/:id/recordings
```

```json
{
  "message": "Call recordings deleted successfully",
  "call_id": "call_01h900000000000000000001",
  "deleted_count": 1,
  "freed_bytes": 256000
}
```

### Bulk delete recordings

```
DELETE /recordings/bulk
```

| Field | Type     | Required | Description                              |
| ----- | -------- | -------- | ---------------------------------------- |
| `ids` | string[] | ✅       | Recording IDs to delete (1–100 items)    |

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/recordings/bulk" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["rec_01h900000000000000000001", "rec_01h900000000000000000002"] }'
```

```json
{
  "message": "Recordings deleted successfully",
  "deleted_count": 2,
  "freed_bytes": 512000
}
```

---

## List Workspace Recordings

```
GET /recordings
```

| Query Parameter | Type   | Description                                 |
| --------------- | ------ | ------------------------------------------- |
| `call_id`       | string | Filter by call ID                           |
| `from`          | string | Start of date range (ISO 8601)              |
| `to`            | string | End of date range (ISO 8601)                |
| `search`        | string | Text search                                 |
| `page`          | number | Page number (default `1`)                   |
| `limit`         | number | Items per page (default `20`)               |
| `sort_field`    | string | Sort field                                  |
| `sort_order`    | string | `asc` or `desc`                             |

---

## Transcriptions

### Get the transcription of a call

```
GET /calls/:id/transcription
```

Returns the dialogue timeline (speaker, channel, confidence, timestamps), the full text and AI metadata.

### Delete the transcription of a call

```
DELETE /calls/:id/transcription
```

```json
{
  "message": "Call transcription deleted successfully",
  "call_id": "call_01h900000000000000000001"
}
```

### Bulk delete transcriptions

```
DELETE /transcriptions/bulk
```

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/transcriptions/bulk" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["trans_01h900000000000000000001", "trans_01h900000000000000000002"] }'
```

---

## Zero-Retention Workflow

Combine webhooks with the delete endpoints to keep recordings only in storage you control:

1. Subscribe to the [`call.recording.ready`](/developers/webhooks/event-catalog#callrecordingready) webhook.
2. When it arrives, verify the `X-Webhook-Signature` and **immediately download** the file from the presigned `url`.
3. Store the file in your own S3/GCS bucket, data warehouse or on-premise storage.
4. Call `DELETE /calls/:id/recordings/:recording_id` (and `DELETE /calls/:id/transcription` if needed) according to your data retention policy.

```javascript
app.post("/webhooks/firetell", async (req, res) => {
  // verify X-Webhook-Signature first (see Webhooks overview)
  const { event, data } = req.body;

  if (event === "call.recording.ready") {
    // data.url is presigned and expires after 2 hours: download right away
    const audio = await fetch(data.url).then((r) => r.arrayBuffer());
    await archiveToPrivateStorage(`recordings/${data.call_id}.${data.format}`, audio);

    // Delete the cloud copy per your retention policy
    await fetch(
      `https://${WORKSPACE_ID}.firetell.app/api/v1/calls/${data.call_id}/recordings/${data.recording_id}`,
      { method: "DELETE", headers: { Authorization: `ApiKey ${process.env.FIRETELL_API_KEY}` } },
    );
  }

  res.status(200).send("OK");
});
```
