API Overview

Everything you need to know before making your first API request.

Base URL

All API endpoints are prefixed with /v1/. Use the following base URL for all requests:

https://api.audiodelivery.net/v1/

Authentication

Most API requests require authentication via a Bearer token in the Authorization header. If you’re using ADN web components with a Client-Side API key, the components handle authentication automatically — this section applies to direct API requests.

Authorization: Bearer your_api_key_here

A few upload and playback endpoints are authorized by a session ID in the URL instead of a Bearer token, and take no Authorization header: GET /v1/upload_session/:upload_session_id, POST /v1/upload/:upload_session_id/track, and GET /v1/play/:play_session_id/:play_track_id. Each is noted on its endpoint reference.

API Key Types

Key type	Use case	Security
API Access	Server-to-server requests — create sessions, manage tracks, configure variants	Keep secret. Never expose in client-side code.
Client-Side	Web components and mobile apps — play audio, upload files	Safe to include in front-end code. Scoped to playback and upload operations only.
Inline Share	Public share links — redirect directly to a single track variant with no Authorization header	The key is in the URL. Anyone with the link can stream until expiry or deletion. Created in the dashboard. See Inline Share.
URL Signing	Sign delivery URLs on your own server for public tracks — no play session or Authorization header	The signing secret stays server-side. Created in the dashboard. See Signing Keys.

Creating API Keys

Create your first API Access key from the Settings page in the AudioDN dashboard. With that key you can then generate Client-Side (player and uploader) keys server-to-server via POST /v1/api_key. Inline Share and URL Signing keys are not managed through the API — create them from Settings → API Keys in the dashboard.

Request Format

All request and response bodies use JSON. Include the Authorization header on every authenticated request (see the exceptions above), and set Content-Type: application/json when sending a request body. Here’s an example creating a play session across every platform:

Example Request

curl -X POST "https://api.audiodelivery.net/v1/play_session/collection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}'

const payload = {
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
};

const response = await fetch('https://api.audiodelivery.net/v1/play_session/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();

import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/collection")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/collection")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/play_session/collection"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Responses

Successful responses include “ok”: true along with the requested data. Errors return “ok”: false with a message and a unique request ID for debugging:

Success

{
"ok": true,
...
}

Error

{
"ok": false,
"message": "Description of what went wrong",
"api_request_id": "uuid"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — check the request body or parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — the API key doesn’t have permission for this operation
404	Not found — the resource doesn’t exist or isn’t accessible
410	Gone — the session has expired
500	Internal server error — retry or contact support

Pagination

List endpoints return all matching records. For large collections, filter by collection_id or creator_id to scope results.

IDs & Formats

All resource IDs are UUIDs (e.g. 04ea3a34-a0f7-45e8-a711-9c7274490e2e). Timestamps are returned as ISO 8601 strings in UTC.