Gửi request

Base URL, định dạng JSON của request và phản hồi, các header phản hồi, phiên bản và ngừng hỗ trợ, và những gì cần gửi bộ phận hỗ trợ khi có sự cố.

Cập nhật 18 tháng 10, 2026

HILLS API là JSON qua HTTPS. Trang này trình bày những điểm chung của mọi request và phản hồi.

Base URL

https://api.hillsmusic.com/v1

Chỉ có một base URL, dùng cho cả kiểm thử lẫn phân phối. Các cổng white-label cũng phản hồi trên tên miền riêng của chúng.

Base cũ, https://app.hillsmusic.com/api/v1, vẫn nhận cùng đường dẫn, key và trả về cùng phản hồi cho đến ngày 30/04/2027. Sau ngày đó, base cũ ngừng phản hồi. Phản hồi từ base cũ mang header Deprecation và Sunset. Hãy chuyển sang api.hillsmusic.com/v1 ngay bây giờ: chỉ base thay đổi. Xem mục nhật ký thay đổi.

Xác thực

Mọi request đều gửi key của bạn:

Authorization: Bearer hm_live_…

Xem Xác thực. Chỉ gọi API từ server của bạn. API không gửi header CORS, nên trình duyệt không gọi được, và một key nằm trong trang web là một key đã bị lộ.

Đọc dữ liệu

Thao tác đọc là các request GET với query parameter:

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

const url = new URL("https://api.hillsmusic.com/v1/releases");
url.searchParams.set("status", "approved");
url.searchParams.set("limit", "20");
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data } = await res.json();

Danh sách trả về { "data": [ … ] }, đôi khi kèm các trường phân trang. Xem Phân trang. Một đối tượng đơn lẻ trả về { "data": { … } }. Một số phản hồi có trường cấp cao nhất riêng, như GET /me và GET /earnings. Mỗi trang tham chiếu đều cho thấy cấu trúc chính xác.

Gửi dữ liệu

Request POST và PATCH gửi body JSON với Content-Type: application/json:

curl -X POST "https://api.hillsmusic.com/v1/members/invite" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"luna@example.com","fname":"Luna","kind":"artist"}'

const res = await fetch("https://api.hillsmusic.com/v1/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HILLS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "luna@example.com", fname: "Luna", kind: "artist" }),
});
console.log(res.status, await res.json()); // 201 on success

Body không phải JSON hợp lệ sẽ được đọc như body rỗng. Khi đó phản hồi là 400 invalid, với field nêu trường bắt buộc đầu tiên.

Phân phối DDEX là ngoại lệ: chúng gửi một tệp zip hoặc XML, không phải JSON. Xem Phân phối DDEX.

Bạn có thể làm gì

API đọc thành viên, danh mục, doanh thu, thanh toán và smart link của bạn. API ghi dữ liệu ở ba chỗ: mời nghệ sĩ và hãng đĩa, phân phối các lô DDEX, và quản lý endpoint webhook.

API không hỗ trợ tạo hay sửa một bản phát hành theo từng trường. Hãy phân phối bản phát hành dưới dạng DDEX ERN (POST /ddex, khuyến nghị ERN 4.3.2 hoặc 3.8.2), hoặc dùng ứng dụng web.

Định dạng

Thời gian theo ISO 8601, múi giờ UTC, ví dụ 2026-10-13T09:00:00Z.
Ngày như release_date có dạng YYYY-MM-DD.
Tiền tính bằng USD. GET /earnings dùng số thập phân (amount_usd). GET /payouts dùng số cent nguyên (earned_cents, available_cents).
ID là số nguyên. ID sự kiện webhook là UUID.
URL ảnh bìa (cover_url) có chữ ký và hết hạn khoảng 24 giờ sau khi phản hồi. Hãy lấy lại bản phát hành để có URL mới, và đừng lưu URL này.

Header phản hồi

Header	Khi nào	Ý nghĩa
`X-RateLimit-Limit`	Mọi phản hồi	Số request mỗi phút key này được phép gửi.
`X-RateLimit-Remaining`	Mọi phản hồi	Số request còn lại trong phút này.
`Retry-After`	`429`	Số giây cần chờ. Xem Rate limit.
`X-HILLS-Environment`	Mọi phản hồi	Luôn là `production`. Được giữ lại cho các tích hợp có đọc header này.
`Deprecation`, `Sunset`, `Link`	Khi phản hồi dùng thứ sắp bị bỏ	Thời điểm bị đánh dấu ngừng hỗ trợ, thời điểm bị gỡ bỏ, và mục nhật ký thay đổi liên quan.

Phiên bản

Phiên bản nằm trong đường dẫn: /v1. Hãy viết client sao cho bỏ qua các trường nó không biết, để trường mới không làm hỏng client.

Khi cần bỏ một thứ gì đó trong v1, việc này được thông báo trong nhật ký thay đổi kèm ngày ngừng hỗ trợ. Cho đến ngày đó, các phản hồi có dùng đến nó mang header Deprecation (RFC 9745) và Sunset (RFC 8594), cùng một Link với rel="deprecation" trỏ đến mục nhật ký thay đổi. Ví dụ, trường status cũ trên bản phát hành sẽ bị gỡ vào ngày 30/04/2027. Hãy đọc release_status và delivery_state thay thế.

Hãy ghi log các header Deprecation trong client. Nhờ đó bạn biết về một thay đổi trước khi nó làm hỏng bất cứ thứ gì.

Lỗi

Lỗi trả về một mã trạng thái và { "error": "…", "code": "…" }. Hãy rẽ nhánh theo code, không theo nội dung văn bản. Xem Lỗi.

Khi cần hỗ trợ

Phản hồi không mang request ID. Khi liên hệ HILLS Music về một request, hãy gửi:

method và đường dẫn, ví dụ GET /v1/releases/812;
thời điểm, theo UTC;
mã trạng thái và code bạn nhận được;
tiền tố của key (hm_live_ab12cd34), không bao giờ gửi key đầy đủ.

Nhật ký request của key trên trang Developers hiển thị cùng các thông tin này trong 7 ngày gần nhất.