# Metal Archives — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and explore music data including bands, albums, songs, and lyrics, with the ability to discover artist recommendations, view band members and discographies, and look up record label information. Get detailed information about musicians, their releases, and recommendations based on your musical interests.

**Category:** Music | **Website:** [metal-archives.com/](https://metal-archives.com/) | **Docs:** [parse.bot/marketplace/13434b14-c019-43df-8182-fa0619216c4a/metal-archives-com-api](https://parse.bot/marketplace/13434b14-c019-43df-8182-fa0619216c4a/metal-archives-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_album_details

Fetch full details for an album including tracklist with song IDs for lyrics lookup. The album_id comes from search_albums or get_band_discography.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `album_id` | string | Yes | Numeric album ID (from search_albums results[*].album_id or get_band_discography discography[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_album_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"album_id":"<string>"}'
```

### get_artist_details

Fetch full details for an artist/musician including biography and personal information. The artist_id comes from get_band_members results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `artist_id` | string | Yes | Numeric artist ID (from get_band_members current/past/live[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_artist_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"artist_id":"<string>"}'
```

### get_band_details

Fetch full details for a single band by its numeric ID. Returns genre, country, biography, label, status, and years active. The band_id comes from search_bands results or any other endpoint that references bands.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_band_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### get_band_discography

Fetch the discography for a band, optionally filtered by release type. Returns an array of releases with name, type, year, and review score. Returns an empty array if the band has no releases of the requested type.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |
| `tab` | string | No | Filter by release type. Accepted values: all, main, lives, demos, misc. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_band_discography \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>","tab":"<string>"}'
```

### get_band_members

Fetch the current, past, and live/session members for a band. Each member entry includes name, role, and artist_id for drill-down via get_artist_details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_band_members \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### get_band_recommendations

Fetch similar artist recommendations for a band, ordered by similarity score. Each recommendation includes band name, country, genre, and a numeric similarity score.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `band_id` | string | Yes | Numeric band ID (from search_bands results[*].id). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_band_recommendations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"band_id":"<string>"}'
```

### get_label_details

Fetch record label details including address, status, and specialties. The label_id is a numeric identifier.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label_id` | string | Yes | Numeric label ID. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_label_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label_id":"<string>"}'
```

### get_label_roster

Fetch bands signed to a label with pagination. Can retrieve either the current or past roster.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label_id` | string | Yes | Numeric label ID. |
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `past` | boolean | No | If true, fetch the past roster instead of the current roster. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_label_roster \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label_id":"<string>","limit":"<integer>","offset":"<integer>","past":"<boolean>"}'
```

### get_lyrics

Fetch lyrics for a song by its song ID. The song_id comes from get_album_details tracklist[*].song_id. Returns empty lyrics string if no lyrics are available for that song.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `song_id` | string | Yes | Song ID from get_album_details tracklist[*].song_id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/get_lyrics \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id":"<string>"}'
```

### search_albums

Full-text search over album/release titles. Returns paginated results with album title, band name, and release type. Each result carries album_id and band_id for drill-down.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Album title to search for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/search_albums \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

### search_bands

Full-text search over metal band names. Returns paginated results with band name, genre, and country. Each result carries a band ID usable with get_band_details, get_band_discography, get_band_members, and get_band_recommendations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Band name to search for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/search_bands \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```

### search_songs

Full-text search over song titles. Returns paginated results with song title, band, album, and lyrics availability. Each result carries band_id and album_id for drill-down.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Max results to return per page. |
| `offset` | integer | No | Pagination offset (number of results to skip). |
| `query` | string | Yes | Song title to search for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-metal-archives-com-api-13434b14/search_songs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>","query":"<string>"}'
```