Zum Inhalt springen
HILLS API v1 Early Access

API-Referenz

DDEX-Auslieferungen

DDEX-ERN-Batches (empfohlen: 4.3) an Production liefern, vorher testen (es wird nichts angelegt), Direkt-Uploads für große Batches und ihr Status.

DDEX-ERN-Batches (empfohlen: 4.3) an Production liefern, vorher testen (es wird nichts angelegt), Direkt-Uploads für große Batches und ihr Status.

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

  • DDEX-Nachricht oder -Batch testen
  • DDEX-Batch liefern (empfohlen: ERN 4.3)
  • Auslieferungen auflisten
  • Direkt-Upload starten (große Batches)
  • Stand eines Direkt-Uploads
  • Direkt-Upload verwerfen
  • Direkt-Upload committen
  • Status einer Auslieferung

DDEX-Nachricht oder -Batch testen

POST /v1/ddex/validate · Scope: ddex:validate oder ddex:write

Der Testweg: eine .xml (Content-Type: application/xml) oder eine .zip, geprüft wie eine Auslieferung (XML, die HILLS-Regeln, Audio-, Artwork- und Videodateien, UPCs und ISRCs im Abgleich mit dem Katalog). Es wird nichts angelegt: kein Release, keine Aufnahme, kein Artist, kein Code und keine Auslieferung. Der Test erscheint auf der DDEX-Seite im Dashboard (Test reports). Jede Prüfung nach Phase (pass / warning / error / skipped), was HILLS anlegen würde, und das Ergebnis: would_import, would_import_with_warnings, would_be_flagged oder would_be_rejected. ddex:write funktioniert ebenfalls.

Parameter

Parameter Ort Typ Pflicht Beschreibung
member_id query integer Nein Der Artist bzw. das Label, für den der Batch bestimmt ist (ohne Angabe: Ihr eigenes Konto).
name query string Nein Dateiname für einen Raw-Body (Standard batch.zip, bei XML message.xml).

Request-Body

Der Batch: die ZIP-Datei, die Sie an Stores liefern (ERN-XML und die Ressourcen, auf die es verweist), als Raw-Body, eine einzelne .xml oder das Multipart-Feld file (mit member_id als Feld). Content-Types: application/zip, application/xml, multipart/form-data.

Beispielanfrage

curl -X POST "https://api.hillsmusic.com/v1/ddex/validate?member_id=41" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @batch.zip

Antwort 200

{
  "data": {
    "ern_version": "4.3",
    "verdict": "would_be_rejected",
    "summary": {
      "messages": 1,
      "releases": 1,
      "pass": 41,
      "warnings": 1,
      "errors": 2,
      "skipped": 1
    },
    "checks": [
      {
        "stage": "release",
        "label": "Label",
        "status": "error",
        "message": "ReleaseLabelReference is required…",
        "field": "Release/ReleaseLabelReference"
      }
    ]
  }
}

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.
413 too_large: Größer, als ein Test verarbeitet; liefern Sie ihn mit POST /ddex.
429 busy: Zu viele Tests gleichzeitig; versuchen Sie es gleich noch einmal. rate_limited: Retry-After Sekunden warten.

DDEX-Batch liefern (empfohlen: ERN 4.3)

POST /v1/ddex · Scope: ddex:write

Senden Sie die ZIP-Datei, die Sie an Stores liefern: ERN-NewReleaseMessage-XML(s) mit Audio, Cover und Videos, auf die sie verweisen. Als Raw-Body (Content-Type: application/zip, bis 20 GB) oder im Multipart-Feld file (bis 512 MB). Jedes Release wird ein Entwurf bei member_id (ohne Angabe: Ihr eigener Katalog); eine dort bereits vorhandene UPC aktualisiert ihren Entwurf; Takedowns und Updates von Live-Releases warten auf das HILLS-Team. ERN 4.3 (Namespace http://ddex.net/xml/ern/43) wird empfohlen; 4.2, 4.1, 3.8.x (3.8.2, 3.8.1, 3.8) und 3.7 werden akzeptiert und genauso gelesen (der Bericht weist auf die veraltete Version hin); andere Versionen werden abgelehnt. 202 mit der ID der Auslieferung – fragen Sie GET /ddex/{id} ab.

Parameter

Parameter Ort Typ Pflicht Beschreibung
member_id query integer Nein Der Artist bzw. das Label, für den der Batch bestimmt ist (ohne Angabe: Ihr eigenes Konto).
name query string Nein Dateiname für einen Raw-Body (Standard batch.zip).

Request-Body

Der Batch: die ZIP-Datei, die Sie an Stores liefern (ERN-XML und die Ressourcen, auf die es verweist), als Raw-Body, eine einzelne .xml oder das Multipart-Feld file (mit member_id als Feld). Content-Types: application/zip, application/xml, multipart/form-data.

Beispielanfrage

curl -X POST "https://api.hillsmusic.com/v1/ddex?member_id=41" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @batch.zip

Antwort 202

{
  "data": {
    "id": 311,
    "status": "queued",
    "environment": "production",
    "status_url": "/v1/ddex/311"
  }
}

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.
413 too_large: Über 20 GB (Raw-Body) oder 512 MB (Multipart).
429 rate_limited: Retry-After Sekunden warten.

Auslieferungen auflisten

GET /v1/ddex · Scope: ddex:write oder ddex:validate

Ihre letzten 100 DDEX-Auslieferungen, die neuesten zuerst (noch nicht committete Uploads fehlen).

Beispielanfrage

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

Antwort 200

{
  "data": [
    {
      "id": 311,
      "member_id": 41,
      "environment": "production",
      "batch_name": "batch-0001.zip",
      "status": "done",
      "error": null,
      "message_id": "MSG-2026-0001",
      "ern_version": "4.3",
      "message_count": 1,
      "release_count": 1,
      "track_count": 12,
      "created_count": 1,
      "updated_count": 0,
      "flagged_count": 0,
      "left_out_count": 0,
      "release_ids": [
        912
      ],
      "created_at": "2026-10-07T09:00:00Z",
      "started_at": "2026-10-07T09:00:02Z",
      "finished_at": "2026-10-07T09:01:10Z"
    }
  ]
}

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.
429 rate_limited: Retry-After Sekunden warten.

Direkt-Upload starten (große Batches)

POST /v1/ddex/uploads · Scope: ddex:write

Empfohlen für große ZIP-Dateien: Die Datei geht direkt in den Speicher statt über die API. Senden Sie den Dateinamen und die Größe in Bytes (bis 20 GB). Bis 64 MB erhalten Sie eine URL, an die Sie die ganze Datei per PUT senden; darüber eine Teilgröße und eine URL pro Teil: Senden Sie jeden Abschnitt von part_size Bytes (der letzte ist kürzer) per PUT an seine URL, in beliebiger Reihenfolge und parallel. Die URLs gelten 6 Stunden; GET /ddex/uploads/{id} liefert neue für die noch fehlenden Teile. Danach POST /ddex/uploads/{id}/commit. DELETE /ddex/uploads/{id} verwirft einen Upload, den Sie nicht abschließen; nicht committete Uploads werden nach 7 Tagen entfernt.

Request-Body

JSON.

Feld Typ Pflicht Beschreibung
name string Ja Der Dateiname (.zip oder .xml).
size integer Ja Die Dateigröße in Bytes.
member_id integer Nein Der Artist bzw. das Label, für den der Batch bestimmt ist (ohne Angabe: Ihr eigenes Konto).

Beispielanfrage

curl -X POST "https://api.hillsmusic.com/v1/ddex/uploads" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"batch-0001.zip","size":1073741824,"member_id":41}'

Antwort 201

{
  "data": {
    "id": 312,
    "status": "uploading",
    "environment": "production",
    "name": "batch-0001.zip",
    "size": 1073741824,
    "expires_in": 21600,
    "upload": {
      "method": "multipart",
      "url": null,
      "part_size": 16777216,
      "parts": [
        {
          "part_number": 1,
          "url": "https://…"
        }
      ]
    },
    "commit_url": "/v1/ddex/uploads/312/commit"
  }
}

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.

Stand eines Direkt-Uploads

GET /v1/ddex/uploads/{id} · Scope: ddex:write

Ein noch nicht committeter Upload: neue URLs für die noch fehlenden Teile (die ersten laufen nach 6 Stunden ab), received_parts und parts_total. Nach dem Commit: die ID der Auslieferung und status_url.

Parameter

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

Beispielanfrage

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

Antwort 200

{
  "data": {
    "id": 312,
    "status": "uploading",
    "environment": "production",
    "name": "batch-0001.zip",
    "size": 1073741824,
    "expires_in": 21600,
    "upload": {
      "method": "multipart",
      "url": null,
      "part_size": 16777216,
      "parts": [
        {
          "part_number": 7,
          "url": "https://…"
        }
      ]
    },
    "commit_url": "/v1/ddex/uploads/312/commit",
    "received_parts": 63,
    "parts_total": 64
  }
}

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.

Direkt-Upload verwerfen

DELETE /v1/ddex/uploads/{id} · Scope: ddex:write

Verwirft einen Upload, den Sie nicht abschließen, samt der bereits gesendeten Teile. 409, wenn er bereits committet wurde.

Parameter

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

Beispielanfrage

curl -X DELETE "https://api.hillsmusic.com/v1/ddex/uploads/312" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Antwort 200

{
  "data": {
    "id": 312,
    "deleted": true
  }
}

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.
409 already_committed: Bereits committet; kann nicht verworfen werden.
429 rate_limited: Retry-After Sekunden warten.

Direkt-Upload committen

POST /v1/ddex/uploads/{id}/commit · Scope: ddex:write

Prüft, ob jeder Teil in der richtigen Größe angekommen ist, und reiht den Batch genau wie POST /ddex in die Warteschlange ein. 409 upload_incomplete listet fehlende Teile und Teile mit falscher Größe auf (laden Sie sie hoch und committen Sie erneut). 202 mit der ID der Auslieferung; fragen Sie GET /ddex/{id} ab.

Parameter

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

Beispielanfrage

curl -X POST "https://api.hillsmusic.com/v1/ddex/uploads/312/commit" \
  -H "Authorization: Bearer $HILLS_API_KEY"

Antwort 202

{
  "data": {
    "id": 312,
    "status": "queued",
    "environment": "production",
    "status_url": "/v1/ddex/312"
  }
}

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.
409 upload_incomplete: Teile fehlen oder haben die falsche Größe (missing und wrong_size listen sie auf). already_committed: Bereits committet (status_url verweist auf die Auslieferung). commit_in_progress: Ein anderer Commit dieses Uploads läuft.
429 rate_limited: Retry-After Sekunden warten.

Status einer Auslieferung

GET /v1/ddex/{id} · Scope: ddex:write oder ddex:validate

queued → parsing → validating → importing → done / partial / failed, mit einem Eintrag pro Release (angelegt, aktualisiert, an das HILLS-Team übergeben, ausgelassen, Test) und jedem Fehler mit seinem DDEX-Feld. GET /ddex listet Ihre letzten 100 auf.

Parameter

Parameter Ort Typ Pflicht Beschreibung
id path integer Ja Die ID der Auslieferung (aus POST /ddex oder dem Commit).

Beispielanfrage

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

Antwort 200

{
  "data": {
    "id": 311,
    "member_id": 41,
    "environment": "production",
    "status": "partial",
    "message_id": "MSG-2026-0001",
    "ern_version": "4.3",
    "created_count": 1,
    "left_out_count": 1,
    "items": [
      {
        "ref": "R0",
        "title": "Midnight Run",
        "upc": "0602600000017",
        "outcome": "created",
        "release_id": 912,
        "errors": []
      }
    ]
  }
}

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.

Bereit für die Integration?

Beantragen Sie API-Zugang – wir melden uns innerhalb von 1–3 Werktagen bei Ihnen.

API-Zugang beantragen Tarife vergleichen