# Quickstart

> Make an API key in the HILLS web app, check it with /me, then list your releases and read your earnings. About five minutes.

This guide takes you from no key to your first real data. You need a client account on the Enterprise or Custom plan, and a terminal with `curl` or Node 18 or later.

## 1. Make an API key

1. Sign in to the HILLS web app and open **Developers** in the sidebar (`/dashboard/developers`).
2. Choose **New API key**.
3. Give it a name that says where it runs, for example `ERP sync`.
4. Pick its scopes. The defaults are `members:read`, `catalog:read`, `earnings:read`, `payouts:read` and `links:read`. Add `ddex:write`, `ddex:validate` or the webhook scopes only if you need them.
5. Pick when it expires, or leave it with no expiry.
6. Copy the key from the **Copy your API key now** dialog. It is shown once. After that, the list shows only its prefix.

You see **Developers** if you are the account owner, or if your team role has the API keys permission. If the button is greyed out, your plan doesn't include the API: ask your HILLS Music contact.

Keep the key on your server. Put it in an environment variable, never in a web page or an app people download.

```bash
export HILLS_API_KEY="hm_live_…"
```

## 2. Check the key

`GET /me` answers with the account behind the key, the key's name, its scopes and its expiry. It needs no particular scope.

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

```js
const res = await fetch("https://api.hillsmusic.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(res.status, await res.json());
```

A working key answers `200`:

```json
{
  "partner": { "id": 12, "name": "Nova Records", "email": "ops@novarecords.com" },
  "environment": "production",
  "key": {
    "id": 3,
    "name": "ERP sync",
    "prefix": "hm_live_ab12cd34",
    "environment": "production",
    "scopes": ["catalog:read", "earnings:read"],
    "expires_at": null,
    "created_at": "2026-10-01T09:00:00Z"
  }
}
```

`environment` is always `production`. There is one kind of key. If you get `401` or `403` instead, the `code` in the answer says why. See [Errors](https://developer.hillsmusic.com/guides/errors/).

`GET /ping` is another check. It also returns your plan and how many requests you have left this minute. See [Account](https://developer.hillsmusic.com/reference/account/).

## 3. List your releases

`GET /releases` needs `catalog:read`. It returns your artists' and labels' releases, newest first, 50 per page.

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

```js
const res = await fetch("https://api.hillsmusic.com/v1/releases?limit=10", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data, next_cursor } = await res.json();
for (const r of data) console.log(r.id, r.title, r.release_status, r.delivery_state);
```

Each release has `release_status` (where it is in review) and `delivery_state` (where it is in the stores). The values are on [Statuses](https://developer.hillsmusic.com/reference/statuses/). When `next_cursor` is not null, there are more pages. See [Pagination](https://developer.hillsmusic.com/guides/pagination/).

To narrow the list, add `status`, `member_id`, `upc` or `q`. To get one release with its tracks and store-by-store status, call `GET /releases/{id}`. See [Releases](https://developer.hillsmusic.com/reference/releases/).

## 4. Read your earnings

`GET /earnings` needs `earnings:read`. It sums revenue from committed store statements, in USD.

```bash
curl "https://api.hillsmusic.com/v1/earnings?by=store&months=6" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const url = new URL("https://api.hillsmusic.com/v1/earnings");
url.searchParams.set("by", "store"); // month (default), release or store
url.searchParams.set("months", "6"); // 1–60, default 12
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(await res.json());
```

```json
{
  "by": "store",
  "months": 6,
  "currency": "USD",
  "data": [
    { "key": "Spotify", "label": "Spotify", "amount_usd": 1520.42, "member_share_usd": 1064.29, "units": 412003 }
  ]
}
```

`amount_usd` is your total. `member_share_usd` is the part your revenue splits give your artists and labels. See [Earnings](https://developer.hillsmusic.com/reference/earnings/).

## Next steps

- [Authentication](https://developer.hillsmusic.com/guides/authentication/): scopes, expiry, rotating and revoking keys.
- [DDEX delivery](https://developer.hillsmusic.com/guides/ddex/): releases come into HILLS as DDEX ERN batches. The API doesn't create or edit single releases.
- [Webhooks](https://developer.hillsmusic.com/guides/webhooks/): get told when a release is approved, goes live or a statement is published.
- [Rate limits](https://developer.hillsmusic.com/guides/rate-limits/): 120 requests a minute per key on Enterprise.

Source: https://developer.hillsmusic.com/guides/quickstart/