Collections

Les collections sont des conteneurs pour organiser vos pistes audio. Vous pouvez créer, mettre à jour, récupérer et supprimer les informations de collection.

Les réponses incluent deux compagnons en lecture seule de player_color : player_color_light (ajusté pour rester lisible sur un fond clair) et player_color_dark (ajusté pour un fond sombre). Ils sont dérivés de player_color en décalant la luminosité jusqu’à ce que chacun atteigne un contraste minimum, et ne peuvent pas être définis directement.

GET /v1/collection

Renvoie une liste de collections pour une organisation

Paramètres

Nom	Type	Obligatoire	Description
`limit`	number	Facultatif	Nombre maximum de collections à renvoyer
`offset`	number	Facultatif	Nombre de collections à ignorer

Exemple de requête

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.httpMethod = "GET"
    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>;
}

Réponse

{
"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

Renvoie les détails d'une collection spécifique

Paramètres

Nom	Type	Obligatoire	Description
`collection_id`	uuid	Obligatoire	L'identifiant de la collection à récupérer (paramètre de chemin)

Réponse

{
"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

Crée une nouvelle collection

Paramètres

Nom	Type	Obligatoire	Description
`title`	string	Obligatoire	Titre de la collection
`creator_id`	uuid	Facultatif	Identifiant du créateur propriétaire de la collection
`organization_index`	string	Facultatif	Identifiant d'organisation
`metadata`	object	Facultatif	Métadonnées d'organisation pour la collection
`theme`	array of objects	Facultatif	Couleurs extraites des images de couverture
`is_cover_overridable`	boolean	Facultatif	Indique si la couverture de la collection peut être remplacée au niveau de la piste
`is_theme_overridable`	boolean	Facultatif	Indique si les couleurs d'image de la collection peuvent être remplacées au niveau de la piste
`player_color`	string	Facultatif	Couleur du lecteur (couleur hexadécimale)
`player_subtitle`	string	Facultatif	Sous-titre du lecteur

Exemple de requête

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 payload = {
  "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(payload)
});

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 bodyJSON = """
{
  "title": "My Collection",
  "player_subtitle": "Artist Name"
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    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")
        .addHeader("Content-Type", "application/json")
        .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>;
}

Réponse

{
"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

Met à jour une collection existante

Paramètres

Nom	Type	Obligatoire	Description
`collection_id`	uuid	Obligatoire	L'identifiant de la collection à mettre à jour (paramètre de chemin)
`creator_id`	uuid	Facultatif	Identifiant du créateur
`organization_index`	string	Facultatif	Identifiant d'organisation
`title`	string	Facultatif	Titre de la collection
`metadata`	object	Facultatif	Métadonnées d'organisation
`theme`	array of objects	Facultatif	Couleurs extraites des images de couverture
`is_cover_overridable`	boolean	Facultatif	Indique si la couverture de la collection peut être remplacée au niveau de la piste
`is_theme_overridable`	boolean	Facultatif	Indique si les couleurs d'image de la collection peuvent être remplacées au niveau de la piste
`player_color`	string	Facultatif	Couleur du lecteur (couleur hexadécimale)
`player_subtitle`	string	Facultatif	Sous-titre du lecteur

Réponse

{
"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

Supprime une collection de façon logicielle et cascade vers ses pistes

Paramètres

Nom	Type	Obligatoire	Description
`collection_id`	uuid	Obligatoire	L'identifiant de la collection à supprimer (paramètre de chemin)

Supprimer une collection cascade : chaque piste qu’elle contient est supprimée de façon logicielle, avec les variantes et fichiers de chaque piste. Les fichiers retirés sont mis en file pour suppression du stockage d’objets.

Exemple de requête

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>;
}

Réponse

{
"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"
}
}