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 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

{
  "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):

{
  "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)