# Collections | Docs AudioDN

> Points de terminaison API pour créer, mettre à jour, lister et supprimer des collections audio dans AudioDN. Organisez les pistes en albums, playlists ou dossiers.

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

---

# 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"
}
}
```