Audio Files

Manage audio files: list, upload, download, and trigger AI processing.

Endpoints

Method	Endpoint	Scope	Description
GET	/api/v1/audio-files	audio:read	List audio files with filters
GET	/api/v1/audio-files/{id}	audio:read	Get audio file by ID
GET	/api/v1/audio-files/{id}/download-url	audio:download	Generate SAS download URL (15 min expiry)
GET	/api/v1/audio-files/{id}/transcript	audio:read	Get transcript
POST	/api/v1/audio-files/upload-url	audio:write	Request upload URL
POST	/api/v1/audio-files/{id}/process	audio:write	Trigger AI processing
GET	/api/v1/audio-files/{id}/processing-status	audio:read	Check processing status

Query Parameters (List Endpoint)

Parameter	Type	Description
campaignId	string	Filter by campaign
isAICall	bool	Filter AI vs human calls
engagementId	string	Filter by engagement
dateFrom	datetime	Start date range
dateTo	datetime	End date range
page	int	Page number (default: 1)
pageSize	int	Results per page (default: 50, max: 100)

Download Flow

How to download audio files

List audio files using GET /api/v1/audio-files with your desired filters.
Call GET /api/v1/audio-files/{id}/download-url to get a time-limited SAS URL (15 min expiry).
GET the SAS URL directly -- no auth header needed, the signature is embedded in the URL.

Upload Flow

Step 1: Request an upload URL

POST /api/v1/audio-files/upload-url
Authorization: Bearer <token>
Content-Type: application/json

{
  "fileName": "call-2026-03-30.wav",
  "engagementId": "eng_abc123",
  "campaignId": "camp_xyz"   // optional
}

// Response
{
  "audioFileId": "af_98765",
  "uploadUrl": "https://storage.blob.core.windows.net/audio/...?sv=2023&sp=w&sig=...",
  "expiresAt": "2026-03-30T12:15:00Z"
}

Step 2: Upload the file to the SAS URL

PUT <uploadUrl>
x-ms-blob-type: BlockBlob
Content-Type: audio/wav

<binary file content>

The x-ms-blob-type: BlockBlob header is required by Azure Blob Storage. Omitting it will result in a 400 error.

Step 3: Trigger AI processing

POST /api/v1/audio-files/af_98765/process
Authorization: Bearer <token>

// Response
{
  "status": "pending",
  "message": "Processing queued successfully"
}

Processing Status Values

Status	Description
pending	File uploaded, waiting to be picked up
processing	Transcription in progress
evaluating	AI evaluation running on transcript
completed	Processing finished successfully
failed	An error occurred during processing

Polling for status

After triggering processing, poll GET /api/v1/audio-files/{id}/processing-status every few seconds until the status reaches completed or failed. Alternatively, configure a analysis.completed webhook to be notified automatically.