REST API

Call AudioDN directly from your backend or custom clients when you need full control over UI, native players, or server workflows.

When to use it

Custom upload or playback interfaces
Native mobile apps
Server-side entitlement checks before creating play sessions
Catalog management (collections, tracks, keys)

Authentication

API Access key — Authorization: Bearer on your server for catalog and session creation
Client-Side Upload / Player keys — scoped keys that may create upload or play sessions in-client
After an upload session exists, POST /v1/upload/{upload_session_id}/track is authorized by the session ID alone
After a play session exists, GET /v1/play/{play_session_id}/{track_id} needs no Bearer token

Keep API Access keys server-side

Never embed an API Access key in browser or mobile app binaries. Use Client-Side keys or pass session IDs from your backend.

Upload audio

Create a session, register each track, then PUT the bytes:

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_id: 'COLLECTION-ID',
    expires_in: 3600
    // Optional: track: { file_name: 'song.wav' } to also create the first track
  })
});

const { upload_session_id, upload_session } = await response.json();
// Pass upload_session_id to the client (Uploader) or continue with per-track create.

// One request per file. No Authorization header — the upload session ID authorizes it.
const response = await fetch(
  `https://api.audiodelivery.net/v1/upload/${upload_session_id}/track`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ file_name: 'song.wav' })
  }
);

const { track_id, track_upload } = await response.json();
const { method, upload_url } = track_upload;

const file = document.querySelector('input[type="file"]').files[0];

await fetch(upload_url, {
  method,
  headers: { 'Content-Type': file.type },
  body: file
});

// Repeat create-track + PUT for each additional file.

// Processing starts automatically. Prefer webhooks when you can.
// ready = playback-ready (required playable output succeeded). Optional outputs
// such as transcription may still be running until files_completed_at is set.
const terminal = new Set(['ready', 'incomplete', 'error', 'init_error']);
const deadline = Date.now() + 10 * 60 * 1000; // 10-minute timeout
let track;
do {
  if (Date.now() > deadline) throw new Error('Timed out waiting for processing');
  await new Promise((r) => setTimeout(r, 5000));
  const res = await fetch(`https://api.audiodelivery.net/v1/track/${track_id}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_ACCESS_KEY' }
  });
  ({ track } = await res.json());
} while (!terminal.has(track.track_status_id));

if (track.track_status_id === 'error' || track.track_status_id === 'init_error') {
  throw new Error(`Processing failed: ${track.track_status_id}`);
}
// ready or incomplete — a playable file may already be available.
// For per-output state (including optional transcription), see
// GET /v1/track/{track_id}/processing or the Output webhook.

Prefer webhooks over long polling when you can. Full flows: Uploading audio · Upload Sessions.

Access and play audio

Create a play session with the delivery indexes you need (wire field variants), then fetch signed URLs:

// After checking the listener's entitlement on your server:
const response = await fetch('https://api.audiodelivery.net/v1/play_session/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_ACCESS_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    collection_id: 'COLLECTION-ID',
    variants: ['hq', 'lq'],
    is_downloadable: false,
    expires_in: 3600
  })
});

const { play_session_id, tracks, first_track } = await response.json();

const track_id = tracks[0].id;

// No auth needed — the play session ID authorizes the request
const response = await fetch(
  `https://api.audiodelivery.net/v1/play/${play_session_id}/${track_id}`
);

const { variants } = await response.json();
const hq = variants.find((v) => v.variant.index === 'hq' || v.variant.id === 'hq');
// Use hq.url in your custom player

Response entries live under the historical variants array. Use those URLs in your own player. For URL signing without a play session, see Signing Keys — keep the signing secret on the server, and do not pass signed URLs to <audiodn-player>.

Next: Playback & delivery · Play Sessions · Tracks · API overview