# REST API | Docs AudioDN

> Integrate AudioDN from custom web, mobile, and server applications using the v1 REST API.

Source: https://audiodeliverynetwork.com/fr/docs/integration/rest/

---

# 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](/docs/integration/uploading) · [Upload Sessions](/docs/api/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](/docs/api/signing-keys) — keep the signing secret on the server, and do not pass signed URLs to `<audiodn-player>`.

Next: [Playback & delivery](/docs/integration/playback) · [Play Sessions](/docs/api/play-sessions) · [Tracks](/docs/api/tracks) · [API overview](/docs/api)