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.

Aktualisiert 18. Oktober 2026

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.

Authentifizierung

Jede Anfrage sendet Ihren Schlüssel:

Authorization: Bearer hm_live_…

Siehe Authentifizierung. 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:

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

Listen antworten mit { "data": [ … ] }, teils mit zusätzlichen Feldern für die Paginierung. Siehe Paginierung. 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:

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

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.

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

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

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.