> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Recordings

> Record calls, download audio files, and manage recordings via the API

You can record any active call by sending a `start_recording` command. Once the recording finishes, the audio file is stored and made available through the recordings API.

## Starting a Recording

To begin recording, send a `start_recording` [call command](/calling/call-commands#start-recording):

```bash icon="terminal" title="Start recording a call" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "start_recording",
    "format": "mp4"
  }'
```

### Supported Formats

| Format | Description            |
| ------ | ---------------------- |
| `mp4`  | MPEG-4 audio (default) |
| `ogg`  | Ogg Vorbis audio       |
| `webm` | WebM audio             |

## Stopping a Recording

You can stop a recording explicitly with the `stop_recording` command, or the recording ends automatically when the call ends.

```bash icon="terminal" title="Stop recording" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "stop_recording" }'
```

## Recording Lifecycle

Recordings move through these statuses:

| Status       | Description                                      |
| ------------ | ------------------------------------------------ |
| `recording`  | Actively capturing audio                         |
| `processing` | Audio is being processed and uploaded to storage |
| `completed`  | Recording is ready to download                   |
| `failed`     | Processing failed                                |

When a recording reaches the `completed` status, a `calls.recording.completed` webhook is fired.

## List Recordings

Retrieve all recordings for a specific call.

```bash icon="terminal" title="List recordings for a call" theme={null}
curl -X GET https://api.buildwithchirp.com/v1/calls/call_abc123/recordings \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "data": [
    {
      "id": "call_rec_abc123",
      "callId": "call_abc123",
      "status": "completed",
      "format": "mp4",
      "duration": 120,
      "fileUrl": "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=...",
      "fileSize": 1048576,
      "startedAt": "2026-01-15T10:30:00Z",
      "endedAt": "2026-01-15T10:32:00Z",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1
}
```

## Get Recording Details

Retrieve a specific recording by ID. For completed recordings, the response includes a signed download URL that is valid for one hour.

```bash icon="terminal" title="Get a recording" theme={null}
curl -X GET https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "id": "call_rec_abc123",
  "callId": "call_abc123",
  "status": "completed",
  "format": "mp4",
  "duration": 120,
  "fileUrl": "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=...",
  "fileSize": 1048576,
  "startedAt": "2026-01-15T10:30:00Z",
  "endedAt": "2026-01-15T10:32:00Z",
  "createdAt": "2026-01-15T10:30:00Z"
}
```

<Tip>
  The `fileUrl` is a time-limited signed URL. If you need to download the file later, request the recording details again to get a fresh URL.
</Tip>

## Download a Recording

To download the recording file, fetch the `fileUrl` from the get recording response:

```bash icon="terminal" title="Download recording file" theme={null}
curl -o recording.mp4 "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=..."
```

The signed URL is valid for one hour from the time it was generated. After expiration, request the recording details again to get a new URL.

## Delete a Recording

Delete a recording from both storage and the database.

```bash icon="terminal" title="Delete a recording" theme={null}
curl -X DELETE https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "message": "Recording deleted"
}
```

<Warning>
  Deleting a recording is permanent. The audio file is removed from storage and the record is soft-deleted from the database.
</Warning>

## Webhook

When a recording finishes processing, Chirp sends a `calls.recording.completed` webhook to your configured webhook URL. Use this to trigger downstream workflows such as transcription or archival.