# API Overview | AudioDN Docs

> Base URL, authentication, request format, and error handling for the AudioDN API.

Source: https://audiodeliverynetwork.com/docs/api/

---

# 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](/docs/api/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](/docs/api/signing-keys). |

#### Creating API Keys

Create your first **API Access** key from the **Settings** page in the [AudioDN dashboard](https://account.audiodeliverynetwork.com). With that key you can then generate **Client-Side** (player and uploader) keys server-to-server via [POST /v1/api\_key](/docs/api/api-keys). **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 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.