# Music Metadata API — search artists, albums, tracks, labels and works; get artist bios & profiles, discographies, top charts, similar artists, song lyrics, cover art and ISRC lookups, powered by MusicBrainz, Cover Art Archive, iTunes, Apple Music charts, TheAudioDB, ListenBrainz and lrclib

> search artist/album/release/recording/track/label/work (advanced field search supported)
> ReefAPI engine `music-metadata` · 14 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/music-metadata/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /music-metadata/v1/search — 1 credit
search artist/album/release/recording/track/label/work (advanced field search supported)

**Parameters:**
- `query` (string, required) — Search text (advanced field search is supported).
- `type` (enum, optional, default "artist") — Which MusicBrainz entity to search. [one of: artist, release-group, album, release, recording, track, song, label, work]
- `limit` (integer, optional, default 25) — How many results to return (1-100). Clamped to range.
- `offset` (integer, optional, default 0) — Pagination offset (skip N results).

**Returns:** <plural-entity>[] (e.g. artists[]/recordings[]) each w/ id+name(+artist_credit), count (total), offset, type

**Example request body:**
```json
{
  "query": "radiohead",
  "type": "artist"
}
```

### POST /music-metadata/v1/artist_detail — 1 credit
artist + relationships (members/collaborations), discography, aliases, tags

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** artist record + members[], external_urls{}, release-groups[], aliases, tags, ratings

**Example request body:**
```json
{
  "mbid": "a74b1b7f-71a5-4011-9441-d0b5e4122711"
}
```

### POST /music-metadata/v1/album_detail — 1 credit
release (tracklist+labels+ISRCs+discids) or release-group

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `entity` (enum, optional, default "release") — Whether the MBID is a single release or a release-group. [one of: release, release-group]
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** release: title + tracks[]{title, recording_mbid, isrcs} + labels[] + barcode; release-group: title + primary-type + releases[]

**Example request body:**
```json
{
  "mbid": "4b3d18cc-8937-36f4-8de0-481088be58e6",
  "entity": "release"
}
```

### POST /music-metadata/v1/track_detail — 1 credit
recording + ISRCs + work-relations + artist credits

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** recording: title, artist_credit, isrcs[], works[]{title, mbid}, releases[]

**Example request body:**
```json
{
  "mbid": "7c0e3d7c-3944-4b64-87bb-62dba67bea83"
}
```

### POST /music-metadata/v1/label — 1 credit
label detail (country, label-code, aliases, url-rels)

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** label: name, type, country, label-code, aliases, external_urls{}

**Example request body:**
```json
{
  "mbid": "14221f01-8939-4ea0-b8f1-b5a21beae80a"
}
```

### POST /music-metadata/v1/work_detail — 1 credit
work/composition + ISWC + writer relations

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** work: title, iswcs[], writers[]{name, mbid, role}, external_urls{}

**Example request body:**
```json
{
  "mbid": "1b4ff597-f43f-3dac-9f76-0e7b7f38d0d2"
}
```

### POST /music-metadata/v1/isrc_lookup — 1 credit
reverse ISRC -> recordings (cross-catalog key)

**Parameters:**
- `isrc` (string, required) — International Standard Recording Code (2 letters, 3 alphanumerics, 7 digits) — e.g. GBAYE9701274.
- `inc` (string, optional) — Advanced: override the MusicBrainz 'inc' sub-query (relations/sub-resources to embed, '+'-separated). A tuned default is used when omitted.

**Returns:** isrc, recordings[]{title, artist_credit}, count

**Example request body:**
```json
{
  "isrc": "GBAYE9701274"
}
```

### POST /music-metadata/v1/cover_art — 1 credit
Cover-Art-Archive images (multi-resolution) for a release/release-group

**Parameters:**
- `mbid` (string, required) — MusicBrainz id (UUID) of the entity. Find it via the search action.
- `entity` (enum, optional, default "release") — Whether the MBID is a single release or a release-group. [one of: release, release-group]

**Returns:** mbid, entity, images[]{image, thumbnails, front/back}, front_url, has_art, count

**Example request body:**
```json
{
  "mbid": "4b3d18cc-8937-36f4-8de0-481088be58e6",
  "entity": "release"
}
```

### POST /music-metadata/v1/itunes_search — 1 credit
iTunes / Apple Music search for artists, albums or songs — returns genre, high-res artwork, a 30s preview URL, price and store link (country-aware)

**Parameters:**
- `query` (string, required) — Artist, album or song to search.
- `type` (enum, optional, default "artist") — What to search for on the iTunes catalog. [one of: artist, album, song, track, music_video]
- `limit` (integer, optional, default 25) — How many results (1-200). Clamped to range.
- `country` (enum, optional, default "us") — ISO-3166 alpha-2 storefront/market for the chart or search (common set listed; others fall back to 'us'). [one of: us, gb, de, fr, tr, ca, au, jp, br, mx, es, it, nl, se, ru, in, kr, pl, ae, sa]

**Returns:** results[]{kind, artist_name, collection_name, track_name, genre, release_date, duration_ms, price, preview_url, artwork, url}, count

**Example request body:**
```json
{
  "query": "Daft Punk",
  "type": "artist"
}
```

### POST /music-metadata/v1/charts — 1 credit
Apple Music top charts — the most-played songs or albums in a country (updated through the day)

**Parameters:**
- `type` (enum, optional, default "songs") — Which chart to return. [one of: songs, albums]
- `country` (enum, optional, default "us") — ISO-3166 alpha-2 storefront/market for the chart or search (common set listed; others fall back to 'us'). [one of: us, gb, de, fr, tr, ca, au, jp, br, mx, es, it, nl, se, ru, in, kr, pl, ae, sa]
- `limit` (integer, optional, default 25) — Chart depth (1-100). Clamped to range.

**Returns:** chart[]{rank, name, artist_name, artist_id, genres[], release_date, artwork, url}, country, type, updated, count

**Example request body:**
```json
{
  "type": "songs",
  "country": "us",
  "limit": 10
}
```

### POST /music-metadata/v1/artist_profile — 1 credit
Rich artist profile: biography, genre/style/mood, formed year, label, follower/popularity counts, social links and images (TheAudioDB). Pass the MusicBrainz mbid (from search/artist_detail) for an exact match, or an artist name

**Parameters:**
- `mbid` (string, optional) — Artist MusicBrainz id (preferred — exact match).
- `name` (string, optional) — Artist name (used when no mbid is given).

**Returns:** artist{name, biography, genre, style, mood, formed_year, country, label, popularity, followers, social{}, images{}}, found

**Example request body:**
```json
{
  "mbid": "cc197bad-dc9c-440d-a5b5-d52ba2e14234"
}
```

### POST /music-metadata/v1/artist_top_tracks — 1 credit
An artist's most popular tracks (top 10) with album, duration, genre and music-video link (TheAudioDB)

**Parameters:**
- `name` (string, required) — Artist name.

**Returns:** artist, tracks[]{rank, track, album, duration_ms, genre, video}, count

**Example request body:**
```json
{
  "name": "Coldplay"
}
```

### POST /music-metadata/v1/similar_artists — 1 credit
Artists similar to a given artist, ranked by a collaborative listening model (ListenBrainz, CC0). Pass the artist's MusicBrainz mbid

**Parameters:**
- `mbid` (string, required) — Artist MusicBrainz id (from search/artist_detail).
- `limit` (integer, optional, default 25) — How many similar artists (1-100). Clamped.

**Returns:** mbid, similar_artists[]{name, mbid, type, comment, score}, count

**Example request body:**
```json
{
  "mbid": "cc197bad-dc9c-440d-a5b5-d52ba2e14234"
}
```

### POST /music-metadata/v1/lyrics — 1 credit
Song lyrics — both plain text and time-synced (LRC) when available — for an artist + track (lrclib, open). Optionally pass album+duration for an exact match

**Parameters:**
- `artist` (string, required) — Artist name.
- `track` (string, required) — Track / song title.
- `album` (string, optional) — Album name (improves exact-match precision).
- `duration` (integer, optional) — Track length in seconds (exact-match key).

**Returns:** found, artist, track, album, duration, instrumental, plain_lyrics, synced_lyrics

**Example request body:**
```json
{
  "artist": "Daft Punk",
  "track": "Get Lucky"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=music-metadata
- Human docs page: https://reefapi.com/docs/music-metadata
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt