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

# Get Download URL

> Generate a pre-signed URL to download a media file from S3

Generate a pre-signed S3 URL for downloading a media file associated with a recording. Pass the `media_id` to specify which file to download.

## Authentication

Requires an [API key](/authentication) with `recordings:read` scope.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.bota.dev/v1/recordings/rec_abc123/download-url \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "media_id": "med_001"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.bota.dev/v1/recordings/rec_abc123/download-url', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      media_id: 'med_001',
    }),
  });

  const { download_url, content_type, expires_at } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.bota.dev/v1/recordings/rec_abc123/download-url',
      headers={
          'Authorization': 'Bearer sk_live_...',
          'Content-Type': 'application/json',
      },
      json={
          'media_id': 'med_001',
      },
  )

  result = response.json()
  download_url = result['download_url']
  ```
</RequestExample>

## Path Parameters

<ParamField path="id" type="string" required>
  The recording's unique identifier (e.g., `rec_abc123`).
</ParamField>

## Request Body

<ParamField body="media_id" type="string" required>
  The media item to download (e.g., `med_001`). Get available media IDs from the recording's `media` array.
</ParamField>

## Response

Returns a pre-signed S3 download URL along with file metadata and an expiration timestamp.

<ResponseExample>
  ```json 200 theme={null}
  {
    "download_url": "https://bota-uploads.s3.amazonaws.com/proj_xxx/rec_abc123/med_001/audio.opus?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
    "media_id": "med_001",
    "content_type": "audio/opus",
    "file_size_bytes": 1048576,
    "expires_at": "2025-01-15T12:00:00Z"
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "not_found",
      "message": "Recording not found"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Media not yet uploaded"
    }
  }
  ```
</ResponseExample>

## Response Fields

| Field             | Type    | Description                                                             |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| `download_url`    | string  | Pre-signed S3 URL for downloading the file                              |
| `media_id`        | string  | The requested media identifier                                          |
| `content_type`    | string  | MIME type of the file (e.g., `audio/opus`, `image/jpeg`)                |
| `file_size_bytes` | integer | File size in bytes                                                      |
| `expires_at`      | string  | ISO 8601 timestamp when the download URL expires (1 hour from creation) |

## Using the Download URL

The pre-signed URL can be used directly:

```bash cURL theme={null}
# Download the file
curl -o recording.opus "https://bota-uploads.s3.amazonaws.com/..."
```

```javascript Browser theme={null}
// Play audio in browser
const audio = new Audio(download_url);
audio.play();

// Or display image
const img = document.createElement('img');
img.src = download_url;
```

```python Python theme={null}
import requests

# Download the file
response = requests.get(download_url)
with open('recording.opus', 'wb') as f:
    f.write(response.content)
```

<Note>
  The download URL expires after 1 hour. If expired, request a new URL. The media must be in `uploaded` status.
</Note>