Bản phát hành

Danh mục của bạn: các bản phát hành cùng trạng thái, track và việc phân phối trên từng nền tảng.

Base URL https://api.hillsmusic.com/v1. Mọi request đều gửi một API key: Authorization: Bearer hm_live_….

• Liệt kê bản phát hành
• Lấy một bản phát hành

Liệt kê bản phát hành

GET /v1/releases · Scope: catalog:read

Các bản phát hành của nghệ sĩ và hãng đĩa của bạn, mới nhất trước, 50 bản mỗi trang. Gửi lại next_cursor trong cursor để lấy trang tiếp theo; ở trang cuối, giá trị này là null.

Ngừng hỗ trợ: các trường trạng thái theo cách gọi cũ (status trên bản phát hành, stores[key].state trên từng nền tảng, status và previous_status trong phản hồi mô phỏng) bị gỡ bỏ vào ngày 30 tháng 4, 2027. Hãy dùng release_status và delivery_state cho bản phát hành, stores[key].status cho từng nền tảng, và trong phản hồi mô phỏng là release_status, delivery_state và previous_release_status thay thế. Cho đến ngày đó, các phản hồi mang header Deprecation và Sunset. Điều gì thay đổi

Ngừng hỗ trợ: các giá trị cũ của bộ lọc status= là pending, rejected và distributed không còn được chấp nhận vào ngày 30 tháng 4, 2027. Hãy dùng status=in_review, status=changes_requested, và status=approved với delivery_state live hoặc partially_live trong phản hồi thay thế. Cho đến ngày đó, các phản hồi (khi request lọc theo một trong các giá trị cũ) mang header Deprecation và Sunset. Điều gì thay đổi

Parameter

Ví dụ request

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

Phản hồi 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"
}

Lỗi

Lấy một bản phát hành

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

Một bản phát hành cùng các track và, với từng nền tảng, trạng thái (xem Trạng thái), giai đoạn và liên kết. status và stores[key].state giữ cách gọi cũ đến 30/04/2027, khi chúng bị gỡ bỏ; hãy đọc release_status, delivery_state và stores[key].status thay thế.

Ngừng hỗ trợ: các trường trạng thái theo cách gọi cũ (status trên bản phát hành, stores[key].state trên từng nền tảng, status và previous_status trong phản hồi mô phỏng) bị gỡ bỏ vào ngày 30 tháng 4, 2027. Hãy dùng release_status và delivery_state cho bản phát hành, stores[key].status cho từng nền tảng, và trong phản hồi mô phỏng là release_status, delivery_state và previous_release_status thay thế. Cho đến ngày đó, các phản hồi mang header Deprecation và Sunset. Điều gì thay đổi

Parameter

Ví dụ request

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

Phản hồi 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"
      }
    }
  }
}

Lỗi