Faire des requêtes

URL de base, format JSON des requêtes et des réponses, en-têtes de réponse, versions et obsolescences, et quoi transmettre au support en cas de problème.

Mis à jour le 18 octobre 2026

L’API HILLS, c’est du JSON sur HTTPS. Cette page décrit ce que toutes les requêtes et toutes les réponses ont en commun.

URL de base

https://api.hillsmusic.com/v1

Il n’y a qu’une URL de base, pour les tests comme pour les livraisons. Les portails en marque blanche répondent aussi sur leur propre domaine.

L’ancienne base, https://app.hillsmusic.com/api/v1, accepte les mêmes chemins et les mêmes clés, avec les mêmes réponses, jusqu’au 30 avril 2027. Elle cessera ensuite de répondre. Les réponses de l’ancienne base portent les en-têtes Deprecation et Sunset. Passez dès maintenant à api.hillsmusic.com/v1 : seule la base change. Voir l’entrée du journal des modifications.

Authentification

Chaque requête envoie votre clé :

Authorization: Bearer hm_live_…

Voir Authentification. Appelez l’API uniquement depuis votre serveur. Elle n’envoie aucun en-tête CORS, les navigateurs ne peuvent donc pas l’appeler, et une clé placée dans une page web est une clé compromise.

Lire des données

Les lectures sont des requêtes GET avec des paramètres de requête :

curl "https://api.hillsmusic.com/v1/releases?status=approved&limit=20" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const url = new URL("https://api.hillsmusic.com/v1/releases");
url.searchParams.set("status", "approved");
url.searchParams.set("limit", "20");
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data } = await res.json();

Les listes renvoient { "data": [ … ] }, parfois avec des champs de pagination. Voir Pagination. Un objet seul renvoie { "data": { … } }. Quelques réponses ont leurs propres champs de premier niveau, comme GET /me et GET /earnings. Chaque page de la référence montre la forme exacte.

Envoyer des données

Les requêtes POST et PATCH envoient un corps JSON avec Content-Type: application/json :

curl -X POST "https://api.hillsmusic.com/v1/members/invite" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"luna@example.com","fname":"Luna","kind":"artist"}'

const res = await fetch("https://api.hillsmusic.com/v1/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HILLS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "luna@example.com", fname: "Luna", kind: "artist" }),
});
console.log(res.status, await res.json()); // 201 on success

Un corps qui n’est pas du JSON valide est lu comme vide. La réponse est alors 400 invalid, avec field qui désigne le premier champ obligatoire.

Les livraisons DDEX font exception : elles envoient un fichier zip ou XML, pas du JSON. Voir Livraison DDEX.

Ce que vous pouvez faire

L’API lit vos membres, votre catalogue, vos revenus, vos versements et vos smart links. Elle écrit à trois endroits : l’invitation d’artistes et de labels, la livraison de lots DDEX et la gestion des endpoints webhook.

Créer ou modifier une sortie champ par champ ne fait pas partie de l’API. Livrez vos sorties en DDEX ERN (POST /ddex, ERN 4.3 recommandée), ou utilisez l’application web.

Formats

Les heures sont au format ISO 8601 en UTC, par exemple 2026-10-13T09:00:00Z.
Les dates comme release_date sont au format YYYY-MM-DD.
Les montants sont en USD. GET /earnings utilise des montants décimaux (amount_usd). GET /payouts utilise des cents entiers (earned_cents, available_cents).
Les identifiants sont des entiers. Les identifiants d’événements webhook sont des UUID.
Les URL des pochettes (cover_url) sont signées et expirent environ 24 heures après la réponse. Récupérez de nouveau la sortie pour en obtenir une nouvelle, et ne stockez pas l’URL.

En-têtes de réponse

En-tête	Quand	Signification
`X-RateLimit-Limit`	Chaque réponse	Nombre de requêtes par minute autorisées pour cette clé.
`X-RateLimit-Remaining`	Chaque réponse	Requêtes restantes pour cette minute.
`Retry-After`	`429`	Secondes à attendre. Voir Limites de débit.
`X-HILLS-Environment`	Chaque réponse	Toujours `production`. Conservé pour les intégrations qui le lisent.
`Deprecation`, `Sunset`, `Link`	Quand la réponse utilise un élément en voie de disparition	Date de mise en obsolescence, date de retrait et entrée du journal des modifications.

Gestion des versions

La version figure dans le chemin : /v1. Concevez votre client pour qu’il ignore les champs qu’il ne connaît pas : les nouveaux champs ne le casseront pas.

Lorsqu’un élément de la v1 doit disparaître, son retrait est annoncé dans le journal des modifications avec une date de fin. D’ici là, les réponses qui l’utilisent portent les en-têtes Deprecation (RFC 9745) et Sunset (RFC 8594), ainsi qu’un Link avec rel="deprecation" vers l’entrée du journal. Par exemple, l’ancien champ status des sorties disparaît le 30 avril 2027. Lisez plutôt release_status et delivery_state.

Journalisez les en-têtes Deprecation dans votre client. Vous serez ainsi prévenu d’un changement avant qu’il ne casse quoi que ce soit.

Erreurs

Les erreurs renvoient un code de statut et { "error": "…", "code": "…" }. Basez votre logique sur code, pas sur le texte. Voir Erreurs.

Demander de l’aide

Les réponses ne portent pas d’identifiant de requête. Lorsque vous contactez HILLS Music au sujet d’une requête, transmettez :

la méthode et le chemin, par exemple GET /v1/releases/812 ;
l’heure, en UTC ;
le statut et le code obtenus ;
le préfixe de votre clé (hm_live_ab12cd34), jamais la clé complète.

Le journal des requêtes de votre clé, sur la page Developers, affiche les mêmes informations pour les 7 derniers jours.