Skip to main content
POST
/
v1
/
audio:upload
curl --request POST \ --url https://api.coval.dev/v1/audio:upload \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data '{}'
{ "upload_id": "upl_01HRAB8N9G7Q4Y3K2J5W6X1ZTC", "upload_url": "https://uploads.coval.dev/8fce4e70/upl_01HRAB8N9G7Q4Y3K2J5W6X1ZTC?signature=...", "expires_at": "2025-11-03T15:32:00Z", "max_size_bytes": 104857600, "content_type": "audio/wav" }

Authorizations

​
X-API-Key
string
header
required

API key for authentication.

Body

application/json

Request body for POST /v1/audio:upload. All fields are optional; an empty body issues a WAV upload URL.

​
content_type
enum<string>
default:audio/wav

MIME type of the audio that will be uploaded. MUST match the Content-Type header on your subsequent PUT request, otherwise the upload will be rejected.

Available options:
audio/wav,
audio/mp3
Example:

"audio/wav"

​
expected_size_bytes
integer

Optional client-declared size hint in bytes. The presigned URL always enforces the 100 MB hard cap regardless of this value.

Required range: 1 <= x <= 104857600
Example:

12582912

Response

Presigned upload URL issued

Response for POST /v1/audio:upload.

​
upload_id
string
required

Opaque upload identifier. Pass this as upload_id on POST /v1/conversations:submit after you've uploaded bytes to upload_url.

Pattern: ^upl_[0-9A-HJKMNP-TV-Z]{26}$
Example:

"upl_01HRAB8N9G7Q4Y3K2J5W6X1ZTC"

​
upload_url
string<uri>
required

Short-lived presigned PUT URL. PUT the audio bytes here with the matching Content-Type header from content_type.

Example:

"https://uploads.coval.dev/8fce4e70/upl_01HRAB8N9G7Q4Y3K2J5W6X1ZTC?signature=..."

​
expires_at
string<date-time>
required

Absolute UTC timestamp at which the presigned URL stops being valid. The upload_id itself remains resolvable for 7 days from issuance, but you cannot upload bytes after this timestamp.

Example:

"2025-11-03T15:32:00Z"

​
max_size_bytes
integer
required

Hard upper bound on the uploaded payload size, in bytes.

Example:

104857600

​
content_type
enum<string>
required

Content-Type the client must send on the PUT request. Equal to the content_type requested (or default audio/wav).

Available options:
audio/wav,
audio/mp3
Example:

"audio/wav"