metadata-agregator/docs/research/musicbrainz-server/analysis/API.md

# MusicBrainz Server API

## Base Endpoint

`/ws/2/{entity}/{mbid}`

**Version:** 2 (current stable)  
**Protocol:** HTTPS (HTTP redirects to HTTPS)  
**Base URL:** `https://musicbrainz.org/ws/2/`

## Endpoint Reference

### Core Entities (13)

| Entity | Endpoint | Description |
|--------|----------|-------------|
| artist | `/ws/2/artist/{mbid}` | Artists, bands, orchestras, choirs, characters |
| release | `/ws/2/release/{mbid}` | Physical or digital release of recordings |
| recording | `/ws/2/recording/{mbid}` | Unique audio recording |
| release-group | `/ws/2/release-group/{mbid}` | Logical grouping of releases |
| work | `/ws/2/work/{mbid}` | Musical composition or song |
| label | `/ws/2/label/{mbid}` | Record label or imprint |
| area | `/ws/2/area/{mbid}` | Geographic region (country, city, etc.) |
| event | `/ws/2/event/{mbid}` | Concert, festival, or other music event |
| place | `/ws/2/place/{mbid}` | Venue, studio, or other location |
| series | `/ws/2/series/{mbid}` | Ordered sequence of entities |
| instrument | `/ws/2/instrument/{mbid}` | Musical instrument |
| genre | `/ws/2/genre/{mbid}` | Music genre |
| url | `/ws/2/url/{mbid}` | External URL relationship |

### Identifier Lookups (3)

| Lookup | Endpoint | Description |
|--------|----------|-------------|
| discid | `/ws/2/discid/{discid}` | CD table of contents lookup |
| isrc | `/ws/2/isrc/{isrc}` | International Standard Recording Code |
| iswc | `/ws/2/iswc/{iswc}` | International Standard Musical Work Code |

### User Data Endpoints

| Endpoint | Methods | Description |
|----------|---------|-------------|
| `/ws/2/collection` | GET, POST, PUT, DELETE | User collections |
| `/ws/2/{entity}/{mbid}/tags` | GET, POST | User tags |
| `/ws/2/{entity}/{mbid}/ratings` | GET, POST | User ratings (0-100) |
| `/ws/2/{entity}/{mbid}/annotation` | GET | User annotations |

## HTTP Methods

### GET - Lookup

Retrieve a single entity by MBID:

```
GET /ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da
```

### GET - Browse

Browse entities related to another entity:

```
GET /ws/2/release?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da
```

### GET - Search

Search entities using Lucene query syntax:

```
GET /ws/2/artist?query=artist:nirvana AND country:US
```

### POST - Submit

Submit new data (requires authentication):

```
POST /ws/2/recording/{mbid}?client={client_id}
Content-Type: application/json

{
  "isrcs": ["USRC17607839"]
}
```

### PUT - Add to Collection

Add entities to a collection (semicolon-separated MBIDs):

```
PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
```

### DELETE - Remove from Collection

Remove entities from a collection:

```
DELETE /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2}
```

## Query Parameters

### Format Parameter

**Parameter:** `fmt`  
**Values:** `xml`, `json`  
**Default:** `xml`

```
/ws/2/artist/{mbid}?fmt=json
```

### Include Parameters (inc)

Control which related data to include in the response. Multiple values separated by `+`.

**Common Includes (all entities):**
- `aliases` - Alternative names
- `annotation` - Latest annotation
- `tags` - Folksonomy tags
- `user-tags` - Tags submitted by authenticated user
- `genres` - Genre tags
- `user-genres` - Genres submitted by authenticated user
- `ratings` - Average rating
- `user-ratings` - Rating submitted by authenticated user

**Entity-Specific Includes:**

**Artist:**
- `recordings` - Recordings by this artist
- `releases` - Releases by this artist
- `release-groups` - Release groups by this artist
- `works` - Works by this artist
- `artist-rels` - Relationships to other artists
- `label-rels` - Relationships to labels
- `recording-rels` - Relationships to recordings
- `release-rels` - Relationships to releases
- `release-group-rels` - Relationships to release groups
- `url-rels` - Relationships to URLs
- `work-rels` - Relationships to works

**Release:**
- `artist-credits` - Artist credits for the release
- `labels` - Labels for the release
- `recordings` - Recordings on the release
- `release-groups` - Release group for this release
- `media` - Media (discs) in the release
- `discids` - Disc IDs associated with the release
- `isrcs` - ISRCs for recordings on the release

**Recording:**
- `artist-credits` - Artist credits for the recording
- `releases` - Releases containing this recording
- `isrcs` - ISRCs for this recording
- `work-rels` - Works this recording is a performance of

**Release Group:**
- `artist-credits` - Artist credits for the release group
- `releases` - Releases in this group

**Work:**
- `artist-rels` - Artists related to this work (composers, lyricists)
- `recording-rels` - Recordings of this work

**Example:**
```
/ws/2/release/{mbid}?inc=artist-credits+labels+recordings+media
```

### Browse Parameters

Browse entities related to another entity:

**Parameters:**
- `artist={mbid}` - Browse by artist
- `release={mbid}` - Browse by release
- `release-group={mbid}` - Browse by release group
- `recording={mbid}` - Browse by recording
- `work={mbid}` - Browse by work
- `label={mbid}` - Browse by label
- `area={mbid}` - Browse by area
- `collection={mbid}` - Browse by collection
- `track_artist={mbid}` - Browse by track artist

**Example:**
```
/ws/2/recording?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da&limit=100
```

### Pagination Parameters

**Parameters:**
- `limit` - Number of results (max 100, default 25)
- `offset` - Starting offset (default 0)

**Example:**
```
/ws/2/artist?query=nirvana&limit=100&offset=100
```

### Search Parameter

**Parameter:** `query`  
**Syntax:** Lucene query syntax

**Example:**
```
/ws/2/artist?query=artist:nirvana AND country:US AND type:group
```

## Response Formats

### XML Format

**Namespace:** `http://musicbrainz.org/ns/mmd-2.0#`

```xml
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
  <artist id="5b11f4ce-a62d-471e-81fc-a69a8278c7da" type="Group">
    <name>Nirvana</name>
    <sort-name>Nirvana</sort-name>
    <country>US</country>
    <life-span>
      <begin>1987</begin>
      <end>1994-04-05</end>
      <ended>true</ended>
    </life-span>
  </artist>
</metadata>
```

### JSON Format

```json
{
  "id": "5b11f4ce-a62d-471e-81fc-a69a8278c7da",
  "type": "Group",
  "name": "Nirvana",
  "sort-name": "Nirvana",
  "country": "US",
  "life-span": {
    "begin": "1987",
    "end": "1994-04-05",
    "ended": true
  }
}
```

## Authentication

### OAuth2 Bearer Token

**Primary authentication method for user-specific operations.**

**Header:**
```
Authorization: Bearer {access_token}
```

**Token Endpoint:** `https://musicbrainz.org/oauth2/token`  
**Authorization Endpoint:** `https://musicbrainz.org/oauth2/authorize`

**Grant Types:**
- Authorization Code (with PKCE)
- Refresh Token

### HTTP Digest Authentication

**Legacy authentication method, still supported.**

**Header:**
```
Authorization: Digest username="user", realm="musicbrainz.org", ...
```

## OAuth Scopes

| Scope | Description |
|-------|-------------|
| `profile` | Read user profile information |
| `email` | Read user email address |
| `tag` | Submit and modify tags |
| `rating` | Submit and modify ratings |
| `collection` | Create and modify collections |
| `submit_barcode` | Submit barcodes to releases |
| `submit_isrc` | Submit ISRCs to recordings |

## Rate Limiting

**Limits:**
- Maximum 100 items per page
- 1 request per second (recommended)
- Client identification required for POST requests

**Client Identification:**

All POST requests must include a `client` parameter:

```
POST /ws/2/recording/{mbid}?client=MyApp-1.0
```

**Format:** `{application_name}-{version}`

**Rate Limit Headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
```

## CORS Support

**Enabled:** Yes  
**Allowed Origins:** `*`  
**Allowed Methods:** GET, POST, PUT, DELETE  
**Allowed Headers:** Authorization, Content-Type

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid parameters or malformed request |
| 401 | Unauthorized - Authentication required |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Entity does not exist |
| 405 | Method Not Allowed - HTTP method not supported for this endpoint |
| 406 | Not Acceptable - Requested format not available |
| 415 | Unsupported Media Type - Invalid Content-Type |
| 501 | Not Implemented - Feature not yet implemented |
| 503 | Service Unavailable - Server overloaded or maintenance |

**Error Response (JSON):**
```json
{
  "error": "Not Found",
  "help": "For usage, please see: https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2"
}
```

## Example Requests

### Lookup Artist with Releases

```
GET /ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da?inc=releases+release-groups&fmt=json
```

### Search for Recordings

```
GET /ws/2/recording?query=recording:"Smells Like Teen Spirit" AND artist:nirvana&fmt=json
```

### Browse Releases by Artist

```
GET /ws/2/release?artist=5b11f4ce-a62d-471e-81fc-a69a8278c7da&limit=100&offset=0&fmt=json
```

### Submit ISRC

```
POST /ws/2/recording/5b11f4ce-a62d-471e-81fc-a69a8278c7da?client=MyApp-1.0
Authorization: Bearer {token}
Content-Type: application/json

{
  "isrcs": ["USRC17607839"]
}
```

### Add Releases to Collection

```
PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
Authorization: Bearer {token}
```

## Collection Management

Collections allow users to organize entities (releases, artists, etc.).

**List User Collections:**
```
GET /ws/2/collection?fmt=json
Authorization: Bearer {token}
```

**Get Collection Contents:**
```
GET /ws/2/collection/{collection_mbid}/releases?fmt=json
```

**Add to Collection (semicolon-separated MBIDs):**
```
PUT /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2};{mbid3}
```

**Remove from Collection:**
```
DELETE /ws/2/collection/{collection_mbid}/releases/{mbid1};{mbid2}
```

## Best Practices

1. **Always include a User-Agent header** identifying your application
2. **Respect rate limits** - 1 request per second recommended
3. **Use client parameter** for all POST requests
4. **Cache responses** when appropriate
5. **Use inc parameters** to minimize requests
6. **Handle errors gracefully** with exponential backoff
7. **Use HTTPS** for all requests (HTTP redirects to HTTPS)