Update Music Album Details Using Match

You can update metadata for a music album using Plex's match feature and the API. This API command will use the information returned from the search for match API to update the album's metadata.


PUT http://[IP address]:32400/library/metadata/[Music Album ID]/match?guid=[Music Album GUID]&name=[Music Album Name]&year=[Music Album Year]&[List of Tracks]&X-Plex-Token=[PlexToken]


IP addressThe IP address of the Plex Media server.
PlexTokenThe authentication Plex token.
Music Album IDThe key associated with the album to be updated. This key can be found by calling the Get Music Albums for an Artist API command and using the music album ratingKey.
Music Album GUIDThis is the unique identifier returned by the search for match API. Each SearchResult will have a guid attribute. It will be in the format mbid://[string value]. That GUID string is what will be used for this parameter value.
Music Album NameThe name of the album.
Music Album YearThe year the album was released.
List of TracksSee the remarks below.

Return Status

HTTP CodeDescription
200Success - The request was successful.
401Unauthorized - The Plex token provided was not valid.
404Not Found - The Music Album ID value is incorrect.


An XML string is returned, but doesn't provide information about the update. If the status code is 200 and the XML is returned then that would indicated a success.

The response consists of a single MediaContainer element with a few attributes.

MediaContainer Attributes
sizeThe number of music albums.
identifierThe type of item.
mediaTagPrefixPrefix for the media tag.
mediaTagVersionMedia tag version.
Note: This could be a date and time value.


When updating the album you will also need to pass all the album tracks as parameters. This is so each file associated with a track will be identified correctly in Plex.

Each track is one element in an array, with the index of the array being the ID for that track. The ID for the track can get found by calling the search for match API for the album.

Each album SearchResult element returned for a match on the album will return child SearchResult elements. Each of those child elements is one track on the album.

You would use the id attribute for each track SearchResult along with the guid attribute to pass into the API command.

The example below shows how the track list is passed into the command.


Example 1

Update the music album (ABBA's Gold: Greatest Hits) associated with ID 218549 on the Plex Media Server located at the IP address of with the information associated with mbid://61b20e25-3c77-3b23-952b-50f6601f6240 :

PUT b1e8aee6-57eb-457e-807b-f6d6a1bbe2f6&name=Gold: Greatest Hits&year=1992&guid[218550]=mbid://61b20e25-3c77-3b23-952b-50f6601f6240&guid[218551]=mbid://c3dadffa-505f-3828-9f7d-2a1de3e89de0&guid[218552]=mbid://b5834e88-53e7-3de6-9344-19e62f9e3a5e&guid[218553]=mbid://ab1d9b50-a267-3ec3-a6a3-4487bd9d8898&guid[218554]=mbid://9c42ed38-c510-3ecf-8c4b-94ffb86ba2fc&guid[218555]=mbid://9f2db7a5-c327-36e0-b41f-98e277c68a72&guid[218556]=mbid://07fb7820-2465-336e-8197-01647a99f49a&guid[218557]=mbid://28240aa0-2ad2-39af-be8e-6493b457628c&guid[218558]=mbid://64e8f4fd-3b08-36e2-b793-19df5446d48f&guid[218559]=mbid://3364c852-3f71-331d-982f-547052ca5309&guid[218560]=mbid://634a3b37-18e0-334d-bfda-45964d900f70&guid[218561]=mbid://be4b8ef6-5918-3d82-9b8a-a822109590e4&guid[218562]=mbid://e7b39547-4c71-3742-8b3a-d86c255091ca&guid[218563]=mbid://7c1797f3-ad81-37d4-bcc7-b95cb323e87a&guid[218564]=mbid://389290eb-d2e5-36ef-893e-852245ef6578&guid[218565]=mbid://d57c42f7-9814-3d79-9414-e6ad8165f095&guid[218566]=mbid://bf9fd71e-d215-3408-b0e8-cc4ca17ee0f4&guid[218567]=mbid://9530b9e0-8e6e-395d-ba70-d19d79737252&guid[218568]=mbid://8e4570a1-f2fa-3bb7-bec1-98719e060d34&X-Plex-Token=&X-Plex-Token=L6vkd7JtLHjsH5987vYY