Play Sessions

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

POST /v1/play_session/:scope

Creates a new play session for a collection, track, or playlist

Parameters

Name	Type	Required	Description
`scope`	string	Required	One of "collection", "track", or "playlist" (path parameter)
`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')
`playlist_id`	uuid	Optional	ID of the playlist (required if scope is 'playlist')
`is_downloadable`	boolean	Optional	Whether tracks in this session can be downloaded
`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" }
  ],
  "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",
      "image_colors": [],
      "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" }
  ],
  "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", "image_colors": [], "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",
    "image_colors": [],
    "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 if the play session was created with is_downloadable: true. 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 signed download URL. The response body is JSON (not the audio file) when requesting the URL:

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