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

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

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

<a id="list-releases"></a>

## 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](https://developer.hillsmusic.com/vi/changelog/#2026-10-11-status-fields-sunset)

> **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](https://developer.hillsmusic.com/vi/changelog/#2026-10-11-status-fields-sunset)

### Parameter

| Parameter | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `status` | query | `draft` \| `in_review` \| `pending` \| `changes_requested` \| `rejected` \| `approved` \| `distributed` \| `archived` \| `taken_down` | Không | Chỉ trạng thái bản phát hành này: draft, in_review, changes_requested, approved, archived hoặc taken_down. Các tên cũ đã ngừng hỗ trợ, vẫn được chấp nhận đến 30/04/2027: pending (in_review), rejected (changes_requested), distributed (approved và đã lên kệ ở ít nhất một nền tảng). |
| `cursor` | query | string | Không | next_cursor của trang trước. |
| `updated_since` | query | ngày giờ ISO | Không | Thay đổi tại hoặc sau thời điểm này (dùng để đồng bộ). |
| `limit` | query | integer (1–100) | Không | Kích thước trang (mặc định 50). |
| `member_id` | query | integer | Không | Chỉ các bản phát hành của nghệ sĩ hoặc hãng đĩa này. |
| `upc` | query | string | Không | UPC chính xác. |
| `q` | query | string | Không | Tìm theo tên bản phát hành và nghệ sĩ. |

### Ví dụ request

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

### Phản hồi `200`

```json
{
  "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

| Mã trạng thái | Khi nào |
| --- | --- |
| 400 | invalid: một parameter bị sai; field cho biết parameter nào. |
| 401 | unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired. |
| 403 | insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan. |
| 429 | rate_limited: chờ số giây ghi trong Retry-After. |

<a id="get-a-release"></a>

## 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](https://developer.hillsmusic.com/vi/changelog/#2026-10-11-status-fields-sunset)

### Parameter

| Parameter | Vị trí | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Có | Id của bản phát hành. |

### Ví dụ request

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

### Phản hồi `200`

```json
{
  "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

| Mã trạng thái | Khi nào |
| --- | --- |
| 401 | unauthenticated, invalid_key, key_revoked, key_expired hoặc test_keys_retired. |
| 403 | insufficient_scope: key thiếu scope; scope cho biết scope nào. account_inactive hoặc api_not_in_plan. |
| 404 | not_found: không tồn tại, hoặc không thuộc về bạn. |
| 429 | rate_limited: chờ số giây ghi trong Retry-After. |

Nguồn: https://developer.hillsmusic.com/vi/reference/releases/