Releases

Ihr Katalog: Releases mit Status, Tracks und Auslieferung Store für Store.

Basis-URL https://api.hillsmusic.com/v1. Jede Anfrage sendet einen API-Schlüssel: Authorization: Bearer hm_live_….

Releases auflisten
Release abrufen

Releases auflisten

GET /v1/releases · Scope: catalog:read

Die Releases Ihrer Artists und Labels, die neuesten zuerst, 50 pro Seite. Geben Sie next_cursor als cursor zurück, um die nächste Seite zu erhalten; auf der letzten Seite ist er null.

Veraltet: Am 30. April 2027 werden die Statusfelder mit den alten Wörtern entfernt (status bei Releases, stores[key].state bei jedem Store, status und previous_status in simulate-Antworten). Verwenden Sie stattdessen release_status und delivery_state für das Release, stores[key].status für jeden Store und in simulate-Antworten release_status, delivery_state und previous_release_status. Bis dahin tragen Antworten die Header Deprecation und Sunset. Was sich ändert

Veraltet: Am 30. April 2027 werden die alten Filterwörter pending, rejected und distributed für status= nicht mehr akzeptiert. Verwenden Sie stattdessen status=in_review, status=changes_requested und status=approved mit delivery_state live oder partially_live in der Antwort. Bis dahin tragen Antworten, bei denen die Anfrage mit einem der alten Wörter filtert, die Header Deprecation und Sunset. Was sich ändert

Parameter

Parameter	Ort	Typ	Pflicht	Beschreibung
`status`	query	`draft` \| `in_review` \| `pending` \| `changes_requested` \| `rejected` \| `approved` \| `distributed` \| `archived` \| `taken_down`	Nein	Nur dieser Release-Status: draft, in_review, changes_requested, approved, archived oder taken_down. Veraltete Aliase, akzeptiert bis 30. April 2027: pending (in_review), rejected (changes_requested), distributed (approved und in mindestens einem Store live).
`cursor`	query	string	Nein	next_cursor der vorherigen Seite.
`updated_since`	query	ISO-Datum und -Uhrzeit	Nein	Zu oder nach diesem Zeitpunkt geändert (für die Synchronisierung).
`limit`	query	integer (1–100)	Nein	Seitengröße (Standard 50).
`member_id`	query	integer	Nein	Nur die Releases dieses Artists oder Labels.
`upc`	query	string	Nein	Exakte UPC.
`q`	query	string	Nein	Suche in Titel und Artist.

Beispielanfrage

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

Antwort `200`

{
  "data": [
    {
      "id": 812,
      "title": "Midnight Run",
      "version": null,
      "type": "single",
      "status": "distributed",
      "release_status": "approved",
      "review_stage": null,
      "delivery_state": "partially_live",
      "update_state": "none",
      "stores_live": 12,
      "stores_total": 30,
      "live_at": "2026-10-05T10:12:00Z",
      "artists": "Luna",
      "featured_artists": null,
      "label": "Nova Records",
      "genre": "Pop",
      "upc": "0123456789012",
      "release_date": "2026-11-01",
      "cover_url": "/api/catalog/files/cover/…",
      "member_id": 41,
      "track_count": 1,
      "submitted_at": "2026-10-02T08:00:00Z",
      "created_at": "2026-09-30T08:00:00Z",
      "updated_at": "2026-10-03T08:00:00Z"
    }
  ],
  "next_cursor": "aWQ6ODEy"
}

Fehler

Status	Wann
400	invalid: Ein Parameter ist fehlerhaft; field nennt ihn.
401	unauthenticated, invalid_key, key_revoked, key_expired oder test_keys_retired.
403	insufficient_scope: Dem Schlüssel fehlt der Scope; scope nennt ihn. account_inactive oder api_not_in_plan.
429	rate_limited: Retry-After Sekunden warten.

Release abrufen

GET /v1/releases/{id} · Scope: catalog:read

Ein Release mit seinen Tracks und pro Store Status (siehe Statuswerte), Phase und Link. status und stores[key].state behalten die alten Wörter bis 30. April 2027 und werden dann entfernt; lesen Sie stattdessen release_status, delivery_state und stores[key].status.

Veraltet: Am 30. April 2027 werden die Statusfelder mit den alten Wörtern entfernt (status bei Releases, stores[key].state bei jedem Store, status und previous_status in simulate-Antworten). Verwenden Sie stattdessen release_status und delivery_state für das Release, stores[key].status für jeden Store und in simulate-Antworten release_status, delivery_state und previous_release_status. Bis dahin tragen Antworten die Header Deprecation und Sunset. Was sich ändert

Parameter

Parameter	Ort	Typ	Pflicht	Beschreibung
`id`	path	integer	Ja	Die ID des Releases.

Beispielanfrage

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

Antwort `200`

{
  "data": {
    "id": 812,
    "title": "Midnight Run",
    "type": "single",
    "status": "distributed",
    "release_status": "approved",
    "delivery_state": "partially_live",
    "update_state": "none",
    "stores_live": 1,
    "stores_total": 2,
    "live_at": "2026-10-05T10:12:00Z",
    "upc": "0123456789012",
    "release_date": "2026-11-01",
    "member_id": 41,
    "tracks": [
      {
        "id": 2001,
        "disc_number": 1,
        "position": 1,
        "title": "Midnight Run",
        "isrc": "USRC17607839",
        "explicit": "not_explicit",
        "duration_ms": 201000
      }
    ],
    "stores": {
      "spotify": {
        "status": "live",
        "op": "insert",
        "phase": "done",
        "url": "https://open.spotify.com/album/…",
        "state": "live"
      },
      "apple_music": {
        "status": "delivered",
        "op": "insert",
        "phase": "done",
        "url": null,
        "state": "sent"
      }
    }
  }
}

Fehler

Status	Wann
401	unauthenticated, invalid_key, key_revoked, key_expired oder test_keys_retired.
403	insufficient_scope: Dem Schlüssel fehlt der Scope; scope nennt ihn. account_inactive oder api_not_in_plan.
404	not_found: Existiert nicht oder gehört nicht Ihnen.
429	rate_limited: Retry-After Sekunden warten.

Releases

Releases auflisten

Parameter

Beispielanfrage

Antwort 200

Fehler

Release abrufen

Parameter

Beispielanfrage

Antwort 200

Fehler

Bereit für die Integration?

Antwort `200`

Antwort `200`