API Reference

Recordings API

Read and manage call recordings produced by completed voice sessions. Each recording is a single WAV file. The bytes never travel through the API; GET /recordings/{id}/audio returns a short-lived signed download URL, suitable for embedding in a player or piping into your own pipeline. Use the recordings:read scope for reads and recordings:write for delete.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 4
Scopes: recordings:readrecordings:write

GET/recordings

Page through every recording for the calling account, newest first.

List Recordings

Returns a paginated list of recordings owned by the calling account, ordered by created_at DESC. Each row carries metadata: duration, size, the associated call ID, and a status field that flips to ready once the WAV finishes uploading.

Path & Query

offsetintegeroptional
Number of results to skip. Must be >= 0. Defaults to 0.
limitintegeroptional
Maximum number of results to return. Must be in [1, 1000]. Defaults to 50.

Errors

401Unauthorized

Missing or invalid API key on the request.

Send X-API-Key: '<'api_key'>' with a key that has the recordings:read scope.

403Forbidden

API key is missing the recordings:read scope.

Mint a key with recordings:read (and recordings:write for delete).

422Unprocessable Entity

offset is negative or limit is outside [1, 1000].

Send offset >= 0 and 1 <= limit <= 1000.

Request

json

curl -X GET 'https://api.aethexai.com/api/v1/recordings?limit=50&offset=0' \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "data": [
    {
      "id": "rec-uuid",
      "call_id": "call-uuid",
      "format": "wav",
      "duration_seconds": 125.4,
      "size_bytes": 2008640,
      "status": "completed",
      "created_at": "2026-05-08T14:32:05Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/recordings/:recording_id

Fetch metadata for one recording by ID, scoped to the calling account.

Get Recording

Returns a single recording by ID. Cross-account lookups return 404. To download the audio, call GET /recordings/{id}/audio; this endpoint never returns bytes.

Path & Query

recording_idstring (uuid)required
The recording UUID.

Errors

401Unauthorized

Missing or invalid API key on the request.

Send X-API-Key: '<'api_key'>'.

403Forbidden

API key is missing the recordings:read scope.

Mint a key with recordings:read.

404Not Found

No recording with that ID exists for the calling account. It was never written, was deleted, or belongs to another account.

Verify the recording_id against GET /recordings for the same key.

422Unprocessable Entity

recording_id is not a valid UUID.

Pass the UUID exactly as returned by GET /recordings.

Request

json

curl -X GET https://api.aethexai.com/api/v1/recordings/rec-uuid \
  -H "X-API-Key: YOUR_KEY"

200 Response

json

{
  "id": "rec-uuid",
  "call_id": "call-uuid",
  "format": "wav",
  "duration_seconds": 125.4,
  "size_bytes": 2008640,
  "status": "completed",
  "created_at": "2026-05-08T14:32:05Z"
}

GET/recordings/:recording_id/audio

Returns a 1-hour signed download URL for the WAV.

Get Audio URL

Mints a time-limited signed download URL for the audio. The URL expires 3600 seconds (1 hour) after issue. Use it directly with any HTTP client; no Aethex auth header is needed on the download URL itself, but minting the URL still requires the recordings:read scope. The bytes never travel through the API; the download goes straight from storage to the caller.

Path & Query

recording_idstring (uuid)required
The recording UUID.

Errors

401Unauthorized

Missing or invalid API key. The mint endpoint always requires authentication even though the returned URL itself is signed.

Send X-API-Key: '<'api_key'>' on the API call.

403Forbidden

API key is missing the recordings:read scope.

Mint a key with recordings:read.

404Not Found

No recording with that ID exists for the caller's account.

Confirm the recording_id via GET /recordings.

410URL expired

The download URL has expired (one hour after issue).

Call GET /recordings/{id}/audio again to mint a fresh URL right before download.

502Could not generate download URL

A transient failure prevented the signed download URL from being generated.

Retry with backoff. If it persists, contact our team at [email protected] with the recording_id and timestamp.

DELETE/recordings/:recording_id

Permanently remove a recording from your account.

Delete Recording

Permanently removes a recording from your account. After this returns, the recording no longer appears in GET /recordings and cannot be downloaded via GET /recordings/{id}/audio. Useful for GDPR right-to-be-forgotten requests and other compliance cleanups. Requires the recordings:write scope.

Path & Query

recording_idstring (uuid)required
The recording UUID.

Errors

401Unauthorized

Missing or invalid API key on the request.

Send X-API-Key: '<'api_key'>'.

403Forbidden

API key is missing the recordings:write scope.

Mint a key with recordings:write (separate from recordings:read).

404Not Found

No recording with that ID exists for the caller's account.

Confirm the recording_id via GET /recordings before retrying.

422Unprocessable Entity

recording_id is not a valid UUID.

Pass the UUID exactly as returned by GET /recordings.