# Anfragen senden

> Basis-URL, JSON-Format von Anfragen und Antworten, Response-Header, Versionierung und Abkündigungen – und was Sie dem Support senden, wenn etwas hakt.

Die HILLS API spricht JSON über HTTPS. Diese Seite beschreibt, was alle Anfragen und Antworten gemeinsam haben.

## Basis-URL

```
https://api.hillsmusic.com/v1
```

Es gibt eine Basis-URL, für Tests und Auslieferungen gleichermaßen. White-Label-Portale antworten zusätzlich unter ihrer eigenen Domain.

Die alte Basis-URL, `https://app.hillsmusic.com/api/v1`, akzeptiert dieselben Pfade und Schlüssel und liefert dieselben Antworten bis zum **30. April 2027**. Danach antwortet sie nicht mehr. Antworten der alten Basis-URL tragen die Header `Deprecation` und `Sunset`. Wechseln Sie jetzt zu `api.hillsmusic.com/v1`: Nur die Basis-URL ändert sich. Siehe den [Changelog-Eintrag](https://developer.hillsmusic.com/de/changelog/#2026-10-11-api-and-mcp-hosts).

## Authentifizierung

Jede Anfrage sendet Ihren Schlüssel:

```
Authorization: Bearer hm_live_…
```

Siehe [Authentifizierung](https://developer.hillsmusic.com/de/guides/authentication/). Rufen Sie die API ausschließlich von Ihrem Server aus auf. Sie sendet keine CORS-Header, Browser können sie also nicht aufrufen – und ein Schlüssel in einer Webseite ist ein offengelegter Schlüssel.

## Daten lesen

Lesezugriffe sind `GET`-Anfragen mit Query-Parametern:

```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();
```

Listen antworten mit `{ "data": [ … ] }`, teils mit zusätzlichen Feldern für die Paginierung. Siehe [Paginierung](https://developer.hillsmusic.com/de/guides/pagination/). Ein einzelnes Objekt antwortet mit `{ "data": { … } }`. Einige Antworten haben eigene Felder auf oberster Ebene, etwa `GET /me` und `GET /earnings`. Jede Referenzseite zeigt die genaue Struktur.

## Daten senden

`POST`- und `PATCH`-Anfragen senden einen JSON-Body mit `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
```

Ein Body, der kein gültiges JSON ist, wird als leer gelesen. Die Antwort ist dann `400 invalid`, wobei `field` das erste Pflichtfeld nennt.

DDEX-Auslieferungen sind die Ausnahme: Sie senden eine ZIP- oder XML-Datei, kein JSON. Siehe [DDEX-Auslieferung](https://developer.hillsmusic.com/de/guides/ddex/).

## Was Sie tun können

Die API liest Ihre Mitglieder, Ihren Katalog, Ihre Erlöse, Auszahlungen und Smart Links. Schreiben kann sie an drei Stellen: Artists und Labels einladen, DDEX-Batches liefern und Webhook-Endpunkte verwalten.

Ein einzelnes Release Feld für Feld anzulegen oder zu bearbeiten, ist mit der API nicht möglich. Liefern Sie Releases als DDEX ERN (`POST /ddex`, empfohlen: ERN 4.3) oder nutzen Sie die Web-App.

## Formate

- **Zeitpunkte** sind ISO 8601 in UTC, zum Beispiel `2026-10-13T09:00:00Z`.
- **Datumsangaben** wie `release_date` haben das Format `YYYY-MM-DD`.
- **Beträge** sind in USD. `GET /earnings` verwendet Dezimalbeträge (`amount_usd`), `GET /payouts` ganze Cent (`earned_cents`, `available_cents`).
- **IDs** sind Ganzzahlen. Die IDs von Webhook-Events sind UUIDs.
- **Artwork-URLs** (`cover_url`) sind signiert und laufen etwa 24 Stunden nach der Antwort ab. Rufen Sie das Release erneut ab, um eine neue zu erhalten, und speichern Sie die URL nicht.

## Response-Header

| Header | Wann | Bedeutung |
| --- | --- | --- |
| `X-RateLimit-Limit` | Jede Antwort | Anfragen pro Minute, die dieser Schlüssel senden darf. |
| `X-RateLimit-Remaining` | Jede Antwort | Verbleibende Anfragen in dieser Minute. |
| `Retry-After` | `429` | Wartezeit in Sekunden. Siehe [Rate Limits](https://developer.hillsmusic.com/de/guides/rate-limits/). |
| `X-HILLS-Environment` | Jede Antwort | Immer `production`. Bleibt für Integrationen erhalten, die ihn auslesen. |
| `Deprecation`, `Sunset`, `Link` | Wenn die Antwort etwas verwendet, das wegfällt | Seit wann es veraltet ist, wann es wegfällt, und der Changelog-Eintrag. |

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

## Versionierung

Die Version steht im Pfad: `/v1`. Bauen Sie Ihren Client so, dass er unbekannte Felder ignoriert. So führen neue Felder nicht zu Fehlern.

Muss etwas in v1 wegfallen, wird es im [Changelog](https://developer.hillsmusic.com/de/changelog/) mit einem Abschaltdatum angekündigt. Bis dahin tragen Antworten, die es verwenden, die Header `Deprecation` (RFC 9745) und `Sunset` (RFC 8594) sowie einen `Link` mit `rel="deprecation"` zum Changelog-Eintrag. Ein Beispiel: Das alte Feld `status` bei Releases fällt am 30. April 2027 weg. Lesen Sie stattdessen `release_status` und `delivery_state`.

Protokollieren Sie `Deprecation`-Header in Ihrem Client. So erfahren Sie von einer Änderung, bevor sie zum Problem wird.

## Fehler

Fehler antworten mit einem Statuscode und `{ "error": "…", "code": "…" }`. Verzweigen Sie anhand von `code`, nicht anhand des Texts. Siehe [Fehler](https://developer.hillsmusic.com/de/guides/errors/).

## Hilfe anfragen

Antworten enthalten keine Request-ID. Wenn Sie HILLS Music wegen einer Anfrage kontaktieren, senden Sie:

- Methode und Pfad, zum Beispiel `GET /v1/releases/812`;
- den Zeitpunkt in UTC;
- den erhaltenen Status und `code`;
- das Präfix Ihres Schlüssels (`hm_live_ab12cd34`), niemals den vollständigen Schlüssel.

Das Anfrageprotokoll Ihres Schlüssels auf der Seite **Developers** zeigt dieselben Angaben für die letzten 7 Tage.

Quelle: https://developer.hillsmusic.com/de/guides/making-requests/