Skip to main content
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:
Start recording a call
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

FormatDescription
mp4MPEG-4 audio (default)
oggOgg Vorbis audio
webmWebM audio

​
Stopping a Recording

You can stop a recording explicitly with the stop_recording command, or the recording ends automatically when the call ends.
Stop recording
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:
StatusDescription
recordingActively capturing audio
processingAudio is being processed and uploaded to storage
completedRecording is ready to download
failedProcessing failed
When a recording reaches the completed status, a calls.recording.completed webhook is fired.

​
List Recordings

Retrieve all recordings for a specific call.
List recordings for a call
curl -X GET https://api.buildwithchirp.com/v1/calls/call_abc123/recordings \
  -H "Authorization: Bearer YOUR_APP_KEY"
Response
{
  "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.
Get a recording
curl -X GET https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
Response
{
  "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"
}
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.

​
Download a Recording

To download the recording file, fetch the fileUrl from the get recording response:
Download recording file
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.
Delete a recording
curl -X DELETE https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
Response
{
  "message": "Recording deleted"
}
Deleting a recording is permanent. The audio file is removed from storage and the record is soft-deleted from the database.

​
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.