--- sidebar_position: 11 title: Audios description: Upload and manage audio files for IVR prompts, hold music, voicemail greetings, and call flow components via the Firetell REST API. --- # Audios Upload and manage audio files used for IVR prompts, hold music, voicemail greetings, and other call flow audio components. Firetell automatically processes uploaded audio into multiple sample rates optimized for telephony. ## Endpoints | Method | Endpoint | Description | | -------- | ------------- | ---------------------- | | `GET` | `/audios` | List all audio files | | `GET` | `/audios/:id` | Get audio file details | | `POST` | `/audios` | Upload an audio file | | `DELETE` | `/audios/:id` | Delete an audio file | ## The Audio Object | Field | Type | Description | | ------------- | ------ | --------------------------------------------------- | | `id` | string | Unique audio identifier (prefixed with `au_`) | | `title` | string | Display name of the audio file | | `url` | string | URL to the best quality audio sample | | `codec` | string | Audio codec (default: `pcm_mulaw`) | | `sample_rate` | number | Original sample rate in Hz (default: `8000`) | | `duration` | number | Duration in seconds | | `file_size` | number | File size in MB | | `mime_type` | string | MIME type (default: `audio/wav`) | | `samples` | array | Array of processed audio samples at different rates | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last update timestamp | ### Audio Sample Object Each audio file is automatically converted into multiple sample rates. The `samples` array contains: | Field | Type | Description | | ---------- | ------ | -------------------------------------------------- | | `rate` | number | Sample rate in Hz (e.g., `8000`, `16000`, `48000`) | | `url` | string | URL to this sample variant | | `key` | string | Storage key identifier | | `size` | number | File size in MB | | `duration` | number | Duration in seconds | --- ## List Audios ``` GET /audios ``` Retrieve a paginated list of all audio files in the workspace. ### Authentication Requires `ApiKey` with any scope. ### Query Parameters | Parameter | Type | Default | Description | | ------------ | ------ | ------------ | ------------------------------------------------------------------- | | `page` | number | `1` | Page number (min: 1) | | `limit` | number | `10` | Items per page (min: 1, max: 100) | | `search` | string | — | Search audio files by title | | `sort_field` | string | `created_at` | Sort field. Allowed: `created_at`, `title`, `duration`, `file_size` | | `sort_order` | string | `desc` | Sort order: `asc` or `desc` | ### Request ```bash curl -X GET "https://{workspace_id}.firetell.app/api/v1/audios?page=1&limit=10&sort_field=created_at&sort_order=desc" \ -H "Authorization: ApiKey sk-YOUR_API_KEY" ``` ### Response ```json { "data": [ { "id": "au_7f3a2b1c9d4e5f6a8b0c1d2e", "title": "Welcome Greeting", "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "codec": "pcm_mulaw", "sample_rate": 8000, "duration": 15, "file_size": 0.24, "mime_type": "audio/wav", "samples": [ { "rate": 48000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "key": "workspace/audios/uuid/48000hz.wav", "size": 1.44, "duration": 15 }, { "rate": 16000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/16000hz.wav", "key": "workspace/audios/uuid/16000hz.wav", "size": 0.48, "duration": 15 }, { "rate": 8000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/8000hz.wav", "key": "workspace/audios/uuid/8000hz.wav", "size": 0.24, "duration": 15 } ], "created_at": "2026-01-15T08:30:00.000Z", "updated_at": "2026-01-15T08:30:00.000Z" } ], "meta": { "total": 3, "page": 1, "limit": 10, "total_pages": 1 } } ``` --- ## Get Audio ``` GET /audios/:id ``` Retrieve details of a specific audio file. ### Authentication Requires `ApiKey` with any scope. ### Path Parameters | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------- | | `id` | string | The audio ID (e.g., `au_7f3a2b1c9d4e5f6a8b0c1d2e`) | ### Request ```bash curl -X GET "https://{workspace_id}.firetell.app/api/v1/audios/au_7f3a2b1c9d4e5f6a8b0c1d2e" \ -H "Authorization: ApiKey sk-YOUR_API_KEY" ``` ### Response ```json { "id": "au_7f3a2b1c9d4e5f6a8b0c1d2e", "title": "Hold Music - Jazz", "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "codec": "pcm_mulaw", "sample_rate": 8000, "duration": 120, "file_size": 1.92, "mime_type": "audio/wav", "samples": [ { "rate": 48000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "key": "workspace/audios/uuid/48000hz.wav", "size": 11.52, "duration": 120 }, { "rate": 16000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/16000hz.wav", "key": "workspace/audios/uuid/16000hz.wav", "size": 3.84, "duration": 120 }, { "rate": 8000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/8000hz.wav", "key": "workspace/audios/uuid/8000hz.wav", "size": 1.92, "duration": 120 } ], "created_at": "2026-02-10T14:22:00.000Z", "updated_at": "2026-02-10T14:22:00.000Z" } ``` ### Error Response ```json { "statusCode": 404, "message": "item not found", "error": "Not Found" } ``` --- ## Upload Audio ``` POST /audios ``` Upload a new audio file. The file is automatically processed and converted into multiple sample rates for optimal telephony playback. ### Authentication Requires `ApiKey` with `full` scope. :::caution Each workspace is limited to a maximum of **100 audio files**. Attempting to upload beyond this limit will return a `403 Forbidden` error. ::: ### Request Body This endpoint uses `multipart/form-data` (not JSON). | Field | Type | Required | Description | | ------- | ------ | -------- | -------------------------------------------- | | `file` | file | ✅ | Audio file to upload (max **3 MB**) | | `title` | string | ✅ | Display name for the audio (1–50 characters) | ### Supported Formats | Format | MIME Type | Notes | | ------ | ------------ | ---------------------------------------- | | WAV | `audio/wav` | Recommended — best quality for telephony | | MP3 | `audio/mpeg` | Widely compatible | | OGG | `audio/ogg` | Compressed alternative | Any file with a MIME type starting with `audio/` is accepted. ### Request ```bash curl -X POST "https://{workspace_id}.firetell.app/api/v1/audios" \ -H "Authorization: ApiKey sk-YOUR_API_KEY" \ -F "file=@/path/to/welcome.wav" \ -F "title=Welcome Greeting" ``` ### Response ```json { "id": "au_9a8b7c6d5e4f3a2b1c0d9e8f", "title": "Welcome Greeting", "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "workspace_id": "yourcompany", "duration": 10, "file_size": 0.16, "samples": [ { "rate": 48000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "size": 0.96, "duration": 10, "key": "workspace/audios/uuid/48000hz.wav" }, { "rate": 16000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/16000hz.wav", "size": 0.32, "duration": 10, "key": "workspace/audios/uuid/16000hz.wav" }, { "rate": 8000, "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/8000hz.wav", "size": 0.16, "duration": 10, "key": "workspace/audios/uuid/8000hz.wav" } ], "created_at": "2026-07-09T08:00:00.000Z", "updated_at": "2026-07-09T08:00:00.000Z" } ``` ### Error Responses **Missing file:** ```json { "statusCode": 400, "message": "file is required", "error": "Bad Request" } ``` **Invalid file type:** ```json { "statusCode": 400, "message": "Only audio accepted", "error": "Bad Request" } ``` **File limit reached:** ```json { "statusCode": 403, "message": "You have reached the maximum limit of 100 files. Please contact support.", "error": "Forbidden" } ``` :::tip For best telephony quality, upload **WAV files** with a sample rate of **16000 Hz** or higher. Firetell will automatically generate optimized versions at 8000 Hz, 16000 Hz, and 48000 Hz. ::: --- ## Delete Audio ``` DELETE /audios/:id ``` Permanently delete an audio file and all its processed samples from storage. ### Authentication Requires `ApiKey` with `full` scope. :::caution This action is irreversible. The audio file and all associated sample rate variants will be permanently deleted. Ensure the audio is not actively used in any call flows before deleting. ::: ### Path Parameters | Parameter | Type | Description | | --------- | ------ | -------------------------------------------------- | | `id` | string | The audio ID (e.g., `au_7f3a2b1c9d4e5f6a8b0c1d2e`) | ### Request ```bash curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/audios/au_7f3a2b1c9d4e5f6a8b0c1d2e" \ -H "Authorization: ApiKey sk-YOUR_API_KEY" ``` ### Response Returns the deleted audio object: ```json { "id": "au_7f3a2b1c9d4e5f6a8b0c1d2e", "title": "Welcome Greeting", "url": "https://s3.amazonaws.com/bucket/workspace/audios/uuid/48000hz.wav", "codec": "pcm_mulaw", "sample_rate": 8000, "duration": 15, "file_size": 0.24, "mime_type": "audio/wav", "samples": [], "created_at": "2026-01-15T08:30:00.000Z", "updated_at": "2026-01-15T08:30:00.000Z" } ``` ### Error Response ```json { "statusCode": 404, "message": "item not found", "error": "Not Found" } ``` --- ## Audio Processing When you upload an audio file, Firetell automatically: 1. **Validates** the file format and sample rate 2. **Converts** the audio into multiple sample rate variants (8000 Hz, 16000 Hz, 48000 Hz) 3. **Stores** all variants in cloud storage for fast access 4. **Selects** the best quality sample as the primary URL The system intelligently selects the optimal audio variant during call playback based on the codec negotiated between endpoints, minimizing real-time transcoding and ensuring the highest quality audio delivery. :::info The minimum accepted sample rate is **8000 Hz**. Files with a lower sample rate will be rejected during upload. :::