Como fazer requisições

A HILLS API é JSON sobre HTTPS. Esta página trata do que toda requisição e toda resposta têm em comum.

URL base

https://api.hillsmusic.com/v1

Existe uma única URL base, tanto para testes quanto para entregas. Os portais white label também respondem no próprio domínio.

A base antiga, https://app.hillsmusic.com/api/v1, aceita os mesmos caminhos e chaves e dá as mesmas respostas até 30 de abril de 2027. Depois disso, ela deixa de responder. As respostas da base antiga trazem os headers Deprecation e Sunset. Migre para api.hillsmusic.com/v1 agora: só a base muda. Veja a entrada do changelog.

Autenticação

Toda requisição envia a sua chave:

Authorization: Bearer hm_live_…

Veja Autenticação. Chame a API apenas a partir do seu servidor. Ela não envia headers CORS, então os navegadores não conseguem chamá-la, e uma chave em uma página web é uma chave vazada.

Leitura de dados

As leituras são requisições GET com parâmetros de query:

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();

As listas respondem { "data": [ … ] }, às vezes com campos de paginação. Veja Paginação. Um objeto único responde { "data": { … } }. Algumas respostas têm campos próprios no nível superior, como GET /me e GET /earnings. Cada página da referência mostra o formato exato.

Envio de dados

As requisições POST e PATCH enviam um corpo JSON com 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

Um corpo que não é JSON válido é lido como vazio. A resposta, nesse caso, é 400 invalid, com field indicando o primeiro campo obrigatório.

As entregas DDEX são a exceção: elas enviam um arquivo zip ou XML, não JSON. Veja Entrega DDEX.

O que você pode fazer

A API lê seus membros, seu catálogo, seus ganhos, seus pagamentos e seus smartlinks. Ela grava em três lugares: no convite de artistas e gravadoras, na entrega de lotes DDEX e no gerenciamento de endpoints de webhook.

Criar ou editar um lançamento avulso campo a campo não faz parte da API. Entregue os lançamentos em DDEX ERN (POST /ddex, ERN 4.3 recomendado) ou use o app web.

Formatos

• Horários seguem a ISO 8601 em UTC, por exemplo 2026-10-13T09:00:00Z.
• Datas como release_date seguem YYYY-MM-DD.
• Valores são em USD. GET /earnings usa valores decimais (amount_usd). GET /payouts usa centavos inteiros (earned_cents, available_cents).
• IDs são inteiros. Os IDs de eventos de webhook são UUIDs.
• URLs de capa (cover_url) são assinadas e expiram cerca de 24 horas após a resposta. Busque o lançamento de novo para obter uma URL nova, e não armazene a URL.

Headers de resposta

Versionamento

A versão fica no caminho: /v1. Construa o seu cliente para ignorar os campos que ele não conhece, assim campos novos não o quebram.

Quando algo na v1 precisa sair, isso é anunciado no changelog com uma data de desativação. Até lá, as respostas que usam esse recurso trazem os headers Deprecation (RFC 9745) e Sunset (RFC 8594), além de um Link com rel="deprecation" para a entrada do changelog. Por exemplo, o campo antigo status dos lançamentos sai em 30 de abril de 2027. Leia release_status e delivery_state no lugar.

Registre os headers Deprecation no log do seu cliente. Assim você fica sabendo de uma mudança antes que ela quebre alguma coisa.

Erros

Os erros respondem com um código de status e { "error": "…", "code": "…" }. Tome decisões com base em code, não no texto. Veja Erros.

Como pedir ajuda

As respostas não trazem um ID de requisição. Ao falar com a HILLS Music sobre uma requisição, envie:

• o método e o caminho, por exemplo GET /v1/releases/812;
• o horário, em UTC;
• o status e o code que você recebeu;
• o prefixo da sua chave (hm_live_ab12cd34), nunca a chave completa.

O log de requisições da sua chave, na página Developers, mostra esses mesmos detalhes dos últimos 7 dias.