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

All 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

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.

Creating API Keys

API keys are created from the Settings page in the AudioDN dashboard.

Request Format

All request and response bodies use JSON. Include the Authorization header on every request, 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 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({"collection_id": "COLLECTION_ID", "variants": ["hq", "lq"]})
});

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 body = {"collection_id": "COLLECTION_ID", "variants": ["hq", "lq"]}
    request.httpBody = try JSONSerialization.data(withJSONObject: body)
    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")
        .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.