# 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.

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](https://developer.hillsmusic.com/fr/changelog/#2026-10-11-api-and-mcp-hosts).

## Authentification

Chaque requête envoie votre clé :

```
Authorization: Bearer hm_live_…
```

Voir [Authentification](https://developer.hillsmusic.com/fr/guides/authentication/). 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 :

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

```js
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](https://developer.hillsmusic.com/fr/guides/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` :

```bash
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"}'
```

```js
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](https://developer.hillsmusic.com/fr/guides/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](https://developer.hillsmusic.com/fr/guides/rate-limits/). |
| `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. |

<a id="versioning"></a>

## 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](https://developer.hillsmusic.com/fr/changelog/) 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](https://developer.hillsmusic.com/fr/guides/errors/).

## 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.

Source: https://developer.hillsmusic.com/fr/guides/making-requests/