# Membros

> Seus artistas e gravadoras: liste-os e convide novos.

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

Seus artistas e gravadoras: liste-os e convide novos.

URL base `https://api.hillsmusic.com/v1`. Toda requisição envia uma chave de API: `Authorization: Bearer hm_live_…`.

- Listar artistas e gravadoras
- Convidar um artista ou gravadora

<a id="list-artists-and-labels"></a>

## Listar artistas e gravadoras

`GET /v1/members` · Escopo: `members:read`

Todos os artistas e gravadoras da sua conta, dos mais recentes para os mais antigos, com o número de lançamentos de cada um.

### Parâmetros

| Parâmetro | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `kind` | query | `artist` \| `label` | Não | Apenas artistas ou apenas gravadoras. |

### Exemplo de requisição

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

### Resposta `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
    }
  ]
}
```

### Erros

| Status | Quando |
| --- | --- |
| 400 | invalid: um parâmetro está errado; field indica qual. |
| 401 | unauthenticated, invalid_key, key_revoked, key_expired ou test_keys_retired. |
| 403 | insufficient_scope: falta à chave o escopo; scope indica qual. account_inactive ou api_not_in_plan. |
| 429 | rate_limited: aguarde Retry-After segundos. |

<a id="invite-an-artist-or-label"></a>

## Convidar um artista ou gravadora

`POST /v1/members/invite` · Escopo: `members:write`

Cria a conta vinculada à sua e envia por e-mail um link (válido por 7 dias) para a pessoa definir a senha. 409 se o e-mail já tiver uma conta.

### Corpo da requisição

JSON.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `email` | string | Sim | O endereço de e-mail. |
| `fname` | string | Sim | Nome, ou o nome da gravadora. |
| `lname` | string | Não | Sobrenome. |
| `kind` | `artist` \| `label` | Sim | O que a conta é. |

### Exemplo de requisição

```bash
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"}'
```

### Resposta `201`

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

### Erros

| Status | Quando |
| --- | --- |
| 400 | invalid: um parâmetro está errado; field indica qual. |
| 401 | unauthenticated, invalid_key, key_revoked, key_expired ou test_keys_retired. |
| 403 | insufficient_scope: falta à chave o escopo; scope indica qual. account_inactive ou api_not_in_plan. |
| 409 | exists: já existe uma conta com este e-mail. |
| 429 | rate_limited: aguarde Retry-After segundos. |

Fonte: https://developer.hillsmusic.com/pt/reference/members/