Collections

Collections are containers for organizing your audio tracks. You can create, update, retrieve, and delete collection information.

Responses include two read-only companions to player_color: player_color_light (adjusted to stay legible on a light background) and player_color_dark (adjusted for a dark background). They are derived from player_color by shifting brightness until each meets a minimum contrast, and cannot be set directly.

GET /v1/collection

Returns a list of collections for an organization

Parameters

Name	Type	Required	Description
`limit`	number	Optional	Maximum number of collections to return
`offset`	number	Optional	Number of collections to skip

Example Request

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

const response = await fetch('https://api.audiodelivery.net/v1/collection', {
  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/collection")!)
    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/collection")
        .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/collection'),
    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,
  "api_request_id": "uuid",
  "count": 0,
  "collections": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "creator_id": "uuid | null",
      "title": "string",
      "organization_index": "string | null",
      "metadata": {},
      "theme": [],
      "player_color": "string | null",
      "player_color_light": "string | null",
      "player_color_dark": "string | null",
      "player_subtitle": "string | null",
      "is_cover_overridable": true,
      "is_theme_overridable": true
    }
  ]
}

GET /v1/collection/:collection_id

Returns details about a specific collection

Parameters

Name	Type	Required	Description
`collection_id`	uuid	Required	The ID of the collection to retrieve (path parameter)

Response

{
  "ok": true,
  "api_request_id": "uuid",
  "collection_id": "uuid",
  "collection": {
    "id": "uuid",
    "organization_id": "uuid",
    "creator_id": "uuid | null",
    "title": "string",
    "organization_index": "string | null",
    "metadata": {},
    "theme": [],
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "player_subtitle": "string | null",
    "is_cover_overridable": true,
    "is_theme_overridable": true
  }
}

POST /v1/collection

Creates a new collection

Parameters

Name	Type	Required	Description
`title`	string	Required	Title of the collection
`creator_id`	uuid	Optional	ID of the creator that owns the collection
`organization_index`	string	Optional	Organization Identifier
`metadata`	object	Optional	Organization metadata for the collection
`theme`	array of objects	Optional	Colors extracted from cover images
`is_cover_overridable`	boolean	Optional	Whether collection cover can be overridden at the track level
`is_theme_overridable`	boolean	Optional	Whether collection image colors can be overridden at the track level
`player_color`	string	Optional	Player color (hex color)
`player_subtitle`	string	Optional	Player subtitle

Example Request

curl -X POST "https://api.audiodelivery.net/v1/collection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Collection", "player_subtitle": "Artist Name"}'

const response = await fetch('https://api.audiodelivery.net/v1/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"title": "My Collection", "player_subtitle": "Artist Name"})
});

const data = await response.json();

import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/collection")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let body = {"title": "My Collection", "player_subtitle": "Artist Name"}
    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 = """{"title": "My Collection", "player_subtitle": "Artist Name"}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/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/collection'),
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({"title": "My Collection", "player_subtitle": "Artist Name"}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Response

{
  "ok": true,
  "api_request_id": "uuid",
  "collection_id": "uuid",
  "collection": {
    "id": "uuid",
    "organization_id": "uuid",
    "creator_id": "uuid | null",
    "title": "string",
    "organization_index": "string | null",
    "metadata": {},
    "theme": [],
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "player_subtitle": "string | null",
    "is_cover_overridable": true,
    "is_theme_overridable": true
  },
  "collection_cover_upload": {
    "method": "POST",
    "upload_url": "string",
    "ttl": 3600,
    "expires_at": "string"
  }
}

PUT /v1/collection/:collection_id

Updates an existing collection

Parameters

Name	Type	Required	Description
`collection_id`	uuid	Required	The ID of the collection to update (path parameter)
`creator_id`	uuid	Optional	ID of the creator
`organization_index`	string	Optional	Organization Identifier
`title`	string	Optional	Title of the collection
`metadata`	object	Optional	Organization metadata
`theme`	array of objects	Optional	Colors extracted from cover images
`is_cover_overridable`	boolean	Optional	Whether collection cover can be overridden at the track level
`is_theme_overridable`	boolean	Optional	Whether collection image colors can be overridden at the track level
`player_color`	string	Optional	Player color (hex color)
`player_subtitle`	string	Optional	Player subtitle

Response

{
  "ok": true,
  "api_request_id": "uuid",
  "collection_id": "uuid",
  "collection": {
    "id": "uuid",
    "organization_id": "uuid",
    "creator_id": "uuid | null",
    "title": "string",
    "organization_index": "string | null",
    "metadata": {},
    "theme": [],
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "player_subtitle": "string | null",
    "is_cover_overridable": true,
    "is_theme_overridable": true
  }
}

DELETE /v1/collection/:collection_id

Soft-deletes a collection and cascades to its tracks

Parameters

Name	Type	Required	Description
`collection_id`	uuid	Required	The ID of the collection to delete (path parameter)

Deleting a collection cascades: every track in it is soft-deleted, together with each track's variants and files. The removed files are queued for deletion from R2 storage.

Example Request

curl -X DELETE "https://api.audiodelivery.net/v1/collection/COLLECTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.audiodelivery.net/v1/collection/COLLECTION_ID', {
  method: 'DELETE',
  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/collection/COLLECTION_ID")!)
    request.httpMethod = "DELETE"
    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/collection/COLLECTION_ID")
        .delete()
        .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.delete(
    Uri.parse('https://api.audiodelivery.net/v1/collection/COLLECTION_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,
  "api_request_id": "uuid",
  "collection_id": "uuid",
  "deleted_collection": {
    "id": "uuid",
    "organization_id": "uuid",
    "creator_id": "uuid | null",
    "title": "string",
    "organization_index": "string | null",
    "metadata": {},
    "theme": [],
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "player_subtitle": "string | null"
  }
}