Schnellstart

Diese Anleitung bringt Sie ohne vorhandenen Schlüssel bis zu Ihren ersten echten Daten. Sie brauchen ein Kundenkonto im Tarif Enterprise oder Custom und ein Terminal mit curl oder Node 18 oder neuer.

1. API-Schlüssel erstellen

1. Melden Sie sich in der HILLS Web-App an und öffnen Sie in der Seitenleiste Developers (/dashboard/developers).
2. Wählen Sie New API key.
3. Geben Sie ihm einen Namen, der sagt, wo er läuft, zum Beispiel ERP sync.
4. Wählen Sie seine Scopes. Voreingestellt sind members:read, catalog:read, earnings:read, payouts:read und links:read. Fügen Sie ddex:write, ddex:validate oder die Webhook-Scopes nur hinzu, wenn Sie sie brauchen.
5. Legen Sie fest, wann er abläuft, oder lassen Sie ihn ohne Ablaufdatum.
6. Kopieren Sie den Schlüssel aus dem Dialog Copy your API key now. Er wird nur einmal angezeigt. Danach zeigt die Liste nur noch sein Präfix.

Developers sehen Sie, wenn Sie Kontoinhaber sind oder Ihre Teamrolle die Berechtigung für API-Schlüssel hat. Ist die Schaltfläche ausgegraut, enthält Ihr Tarif die API nicht: Wenden Sie sich an Ihren Ansprechpartner bei HILLS Music.

Bewahren Sie den Schlüssel auf Ihrem Server auf. Legen Sie ihn in einer Umgebungsvariablen ab, niemals in einer Webseite oder einer App, die andere herunterladen.

export HILLS_API_KEY="hm_live_…"

2. Schlüssel prüfen

GET /me antwortet mit dem Konto hinter dem Schlüssel sowie Name, Scopes und Ablaufdatum des Schlüssels. Ein bestimmter Scope ist dafür nicht nötig.

curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const res = await fetch("https://api.hillsmusic.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(res.status, await res.json());

Ein funktionierender Schlüssel antwortet mit 200:

{
  "partner": { "id": 12, "name": "Nova Records", "email": "ops@novarecords.com" },
  "environment": "production",
  "key": {
    "id": 3,
    "name": "ERP sync",
    "prefix": "hm_live_ab12cd34",
    "environment": "production",
    "scopes": ["catalog:read", "earnings:read"],
    "expires_at": null,
    "created_at": "2026-10-01T09:00:00Z"
  }
}

environment ist immer production, denn es gibt nur eine Art von Schlüssel. Erhalten Sie stattdessen 401 oder 403, nennt der code in der Antwort den Grund. Siehe Fehler.

GET /ping ist eine weitere Prüfung. Sie liefert zusätzlich Ihren Tarif und wie viele Anfragen Ihnen in dieser Minute noch bleiben. Siehe Konto.

3. Releases auflisten

GET /releases braucht catalog:read. Der Endpunkt liefert die Releases Ihrer Artists und Labels, die neuesten zuerst, 50 pro Seite.

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

const res = await fetch("https://api.hillsmusic.com/v1/releases?limit=10", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data, next_cursor } = await res.json();
for (const r of data) console.log(r.id, r.title, r.release_status, r.delivery_state);

Jedes Release hat release_status (wo es in der Prüfung steht) und delivery_state (wo es in den Stores steht). Die Werte finden Sie unter Statuswerte. Ist next_cursor nicht null, gibt es weitere Seiten. Siehe Paginierung.

Um die Liste einzugrenzen, ergänzen Sie status, member_id, upc oder q. Ein einzelnes Release mit seinen Tracks und dem Status Store für Store erhalten Sie mit GET /releases/{id}. Siehe Releases.

4. Erlöse lesen

GET /earnings braucht earnings:read. Der Endpunkt summiert die Erlöse aus verbuchten Store-Abrechnungen in USD.

curl "https://api.hillsmusic.com/v1/earnings?by=store&months=6" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const url = new URL("https://api.hillsmusic.com/v1/earnings");
url.searchParams.set("by", "store"); // month (default), release or store
url.searchParams.set("months", "6"); // 1–60, default 12
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(await res.json());

{
  "by": "store",
  "months": 6,
  "currency": "USD",
  "data": [
    { "key": "Spotify", "label": "Spotify", "amount_usd": 1520.42, "member_share_usd": 1064.29, "units": 412003 }
  ]
}

amount_usd ist Ihre Gesamtsumme. member_share_usd ist der Teil, den Ihre Erlös-Splits Ihren Artists und Labels zuweisen. Siehe Erlöse.

Nächste Schritte

• Authentifizierung: Scopes, Ablaufdatum, Schlüssel rotieren und widerrufen.
• DDEX-Auslieferung: Releases kommen als DDEX-ERN-Batches zu HILLS. Einzelne Releases legt die API nicht an und bearbeitet sie nicht.
• Webhooks: Lassen Sie sich benachrichtigen, wenn ein Release freigegeben wird, live geht oder eine Abrechnung veröffentlicht wird.
• Rate Limits: 120 Anfragen pro Minute und Schlüssel bei Enterprise.