Play Sessions

Play sessions manage audio playback for collections, tracks, or playlists.

Each track's resolved player_color is accompanied by two read-only companions: player_color_light (adjusted to stay legible on a light background) and player_color_dark (adjusted for a dark background), so your player can pick the right one for its theme.

POST /v1/play_session/:scope

Creates a new play session for a collection or track.

Parameters

Name	Type	Required	Description
`scope`	string	Required	"collection" or "track" (path parameter). "playlist" is reserved for a future release and currently returns 400.
`variants`	array of strings	Optional	Variant settings for the play session
`collection_id`	uuid	Optional	ID of the collection (required if scope is 'collection')
`track_id`	uuid	Optional	ID of the track (required if scope is 'track')
`is_downloadable`	boolean	Optional	Requests that tracks in this session be downloadable. This is only honored when the API key also allows downloads (set per key in the dashboard). The stored session value is api_key.is_downloadable AND this request, so a key that forbids downloads always wins — the download endpoint will return 403.
`expires_in`	number	Optional	Session duration in seconds (default: 3600, min: 60, max: 86400)

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"], "expires_in": 3600}'

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"], "expires_in": 3600})
});

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"], "expires_in": 3600}
    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"], "expires_in": 3600}""".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"], "expires_in": 3600}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "play_session": {
    "id": "uuid",
    "creator_id": "uuid | null",
    "variants": ["string"],
    "is_downloadable": false,
    "expires_at": "string"
  },
  "tracks": [
    { "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
  ],
  "first_track": {
    "track_id": "uuid",
    "cover_image": {
      "icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
      "small": { "type": "small", "width": 200, "height": 200, "url": "string" },
      "regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
    },
    "track": {
      "id": "uuid",
      "index": "string",
      "duration": 0,
      "player_title": "string | null",
      "player_subtitle": "string | null",
      "player_color": "string | null",
      "player_color_light": "string | null",
      "player_color_dark": "string | null",
      "theme": [],
      "file_name": "string",
      "info": {},
      "organization_index": "string | null",
      "order": 0,
      "metadata": {},
      "is_dark": false
    },
    "levels": { "levels": [ 0, 0.5, 1 ] },
    "variants": [
      { "path": "string", "url": "string", "variant": { "index": "string" } }
    ]
  },
  "expires_at": "string"
}

The first_track field includes the first track's full playback data (signed streaming URLs, waveform levels, cover image, and variants) so your player can render immediately without a second API call. Use GET /v1/play/:session_id/:track_id to fetch additional tracks on demand.

GET /v1/play_session/:play_session_id

Retrieves details about a play session

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)

Example Request

curl -X GET "https://api.audiodelivery.net/v1/play_session/SESSION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.audiodelivery.net/v1/play_session/SESSION_ID', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();

import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/SESSION_ID")!)
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    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.*

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/SESSION_ID")
        .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.get(
    Uri.parse('https://api.audiodelivery.net/v1/play_session/SESSION_ID'),
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "play_session": {
    "id": "uuid",
    "creator_id": "uuid | null",
    "variants": ["string"],
    "is_downloadable": false,
    "expires_at": "string"
  },
  "tracks": [
    { "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
  ],
  "first_track": {
    "track_id": "uuid",
    "cover_image": { "icon": {}, "small": {}, "regular": {} },
    "track": { "id": "uuid", "index": "string", "duration": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null", "theme": [], "file_name": "string", "info": {}, "organization_index": "string | null", "order": 0, "metadata": {}, "is_dark": false },
    "levels": { "levels": [] },
    "variants": [ { "path": "string", "url": "string", "variant": { "index": "string" } } ]
  }
}

The first_track field includes the first track's full playback data so your player can render immediately without a second API call.

GET /v1/play/:play_session_id/:play_track_id

Retrieves details about a specific track within a play session. No authentication required - the session ID acts as a bearer token.

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)
`play_track_id`	uuid	Required	The ID of the track within the session (path parameter)

Response

{
  "ok": true,
  "play_session_id": "uuid",
  "track_id": "uuid",
  "play_session": {
    "id": "uuid",
    "variants": ["string"],
    "is_downloadable": false,
    "expires_at": "string"
  },
  "cover_image": {
    "icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
    "small": { "type": "small", "width": 200, "height": 200, "url": "string" },
    "regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
  },
  "track": {
    "id": "uuid",
    "index": "string",
    "duration": 0,
    "player_title": "string | null",
    "player_subtitle": "string | null",
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "theme": [],
    "file_name": "string",
    "info": {},
    "organization_index": "string | null",
    "order": 0,
    "metadata": {},
    "is_dark": false
  },
  "levels": { "levels": [ 0, 0.5, 1 ] },
  "variants": [
    { "path": "string", "url": "string", "variant": { "index": "string" } }
  ]
}

GET /v1/play/:play_session_id/:play_track_id/:variant_index/download

Downloads a specific variant of a track. Only available when the session's stored is_downloadable is true (i.e. the API key allows downloads and the session requested them); otherwise returns 403. No authentication required.

Parameters

Name	Type	Required	Description
`play_session_id`	uuid	Required	The ID of the play session (path parameter)
`play_track_id`	uuid	Required	The ID of the track within the session (path parameter)
`variant_index`	string	Required	The index/identifier of the variant to download (path parameter)

Response

Returns a short-lived (30s) signed download URL. The response body is JSON (not the audio file); navigate to download.url to fetch the file. The URL is served with Content-Disposition: attachment so the browser saves the file instead of playing it inline. If the session is not downloadable, the endpoint returns 403 with an error message.

{
  "ok": true,
  "play_session_id": "uuid",
  "track_id": "uuid",
  "download": {
    "variant": "string",
    "url": "string"
  }
}