# Members

> Your artists and labels: list them and invite new ones.

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

Your artists and labels: list them and invite new ones.

Base URL `https://app.hillsmusic.com/api/v1`. Every request sends an API key: `Authorization: Bearer hm_live_…` (production) or `hm_test_…` (sandbox).

- List artists and labels
- Invite an artist or label

## List artists and labels

`GET /api/v1/members` · Scope: `members:read` · Sandbox keys see sandbox data only.

Every artist and label under your account, newest first, with how many releases each has (in the key's environment).

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | query | `artist` \| `label` | No | Only artists or only labels. |

### Example request

```bash
curl "https://app.hillsmusic.com/api/v1/members?kind=artist" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

### Response `200`

```json
{
  "data": [
    {
      "id": 41,
      "email": "luna@example.com",
      "name": "Luna",
      "kind": "artist",
      "status": "active",
      "created_at": "2026-08-02T10:11:00Z",
      "last_login_at": null,
      "releases": 4
    }
  ]
}
```

### Errors

| Status | When |
| --- | --- |
| 400 | invalid: a parameter is wrong; field names it. |
| 401 | unauthenticated, invalid_key, key_revoked or key_expired. |
| 403 | insufficient_scope: the key lacks the scope; scope names it. account_inactive or api_not_in_plan. |
| 429 | rate_limited: wait Retry-After seconds. |

## Invite an artist or label

`POST /api/v1/members/invite` · Scope: `members:write` · Sandbox keys are refused (403 not_in_sandbox).

Creates the account under yours and emails them a link (valid 7 days) to set their password. 409 if the email already has an account.

### Request body

JSON.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | Their email address. |
| `fname` | string | Yes | First name, or the label's name. |
| `lname` | string | No | Last name. |
| `kind` | `artist` \| `label` | Yes | What they are. |

### Example request

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

### Response `201`

```json
{
  "ok": true,
  "id": 57
}
```

### Errors

| Status | When |
| --- | --- |
| 400 | invalid: a parameter is wrong; field names it. |
| 401 | unauthenticated, invalid_key, key_revoked or key_expired. |
| 403 | insufficient_scope: the key lacks the scope; scope names it. account_inactive or api_not_in_plan. not_in_sandbox: a sandbox key (hm_test_…) can't do this. |
| 409 | exists: There's already an account with this email. |
| 429 | rate_limited: wait Retry-After seconds. |

Source: https://developer.hillsmusic.com/reference/members/