Audio Upload

Base URL for your account: https://cpaas.studio/api/v1

POST /api/v1/voice/audio/upload

Uploads a voice audio file to your Audio Library, ready to select as a Voice Broadcast's message. Requires a key scoped to voice.obd or all.

File uploads only — this endpoint does not accept GET, unlike the rest of this API.

Parameters

Param	Type	Required	Notes
`name`	string, max 100	yes	A label for the asset — shown wherever you browse your audio library.
`file`	file (WAV)	yes	multipart/form-data. Must be a WAV file. Size limit is enforced server-side.
`reference`	string, max 64	no	Your own identifier for this asset. Stored as-is and echoed back on this response and on Audio Status lookups — not validated for uniqueness.

Request example

curl -X POST "https://cpaas.studio/api/v1/voice/audio/upload" \
  -H "X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "name=Welcome Greeting" \
  -F "reference=customer-ref-001" \
  -F "file=@/path/to/greeting.wav"

<?php
$ch = curl_init('https://cpaas.studio/api/v1/voice/audio/upload');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-KEY: cpk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'name' => 'Welcome Greeting',
        'reference' => 'customer-ref-001',
        'file' => new CURLFile('/path/to/greeting.wav', 'audio/x-wav', 'greeting.wav'),
    ],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Success response (`data`)

{
    "audio_uid": "AUD7K2M9QX4WQ",
    "name": "Welcome Greeting",
    "reference": "customer-ref-001",
    "status": "pending",
    "duration_seconds": 8,
    "size_bytes": 128000,
    "format": "wav",
    "created_at": "2026-08-14T12:00:00+00:00"
}

Errors

Code	Status	When
`REQ_VALIDATION_FAILED`	422	Missing/invalid name, missing or non-WAV file, file too large.
`SYS_INTERNAL_ERROR`	500	Unexpected failure during storage/processing.

Notes

An uploaded asset starts as "pending" unless your API key has auto-approval enabled — that's a setting on the key itself, not a request parameter.
A "pending" asset cannot be used in a broadcast until approved — poll Audio Status.
audio_uid is an opaque string identifier — never sequential, never predictable from another asset's uid.

Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.

Get In Touch