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

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

{
  "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

curl -X GET "https://{workspace_id}.firetell.app/api/v1/audios/au_7f3a2b1c9d4e5f6a8b0c1d2e" \
  -H "Authorization: ApiKey sk-YOUR_API_KEY"

Response

{
  "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

{
  "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

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

{
  "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:

{
  "statusCode": 400,
  "message": "file is required",
  "error": "Bad Request"
}

Invalid file type:

{
  "statusCode": 400,
  "message": "Only audio accepted",
  "error": "Bad Request"
}

File limit reached:

{
  "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

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:

{
  "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

{
  "statusCode": 404,
  "message": "item not found",
  "error": "Not Found"
}

Audio Processing

When you upload an audio file, Firetell automatically:

Validates the file format and sample rate
Converts the audio into multiple sample rate variants (8000 Hz, 16000 Hz, 48000 Hz)
Stores all variants in cloud storage for fast access
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.

Endpoints​

The Audio Object​

Audio Sample Object​

List Audios​

Authentication​

Query Parameters​

Request​

Response​

Get Audio​

Authentication​

Path Parameters​

Request​

Response​

Error Response​

Upload Audio​

Authentication​

Request Body​

Supported Formats​

Request​

Response​

Error Responses​

Delete Audio​

Authentication​

Path Parameters​

Request​

Response​

Error Response​

Audio Processing​

Endpoints

The Audio Object

Audio Sample Object

List Audios

Authentication

Query Parameters

Request

Response

Get Audio

Authentication

Path Parameters

Request

Response

Error Response

Upload Audio

Authentication

Request Body

Supported Formats

Request

Response

Error Responses

Delete Audio

Authentication

Path Parameters

Request

Response

Error Response

Audio Processing