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/{id}/match?guid={guid}&name={name}&year={year}&{tracks}&X-Plex-Token={plex_token}


ip_addressThe IP address of the Plex Media server.
plex_tokenThe Plex token.
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.
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.
nameThe name of the album.
yearThe year the album was released.
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.


curl -X PUT http://{ip_address}:32400/library/metadata/{id}/match?guid={guid}&name={name}&year={year}&{tracks}&X-Plex-Token={plex_token}
import requests
plex_url = http://{ip_address}:32400/library/metadata/{id}/match?guid={guid}&name={name}&year={year}&{tracks}&X-Plex-Token={plex_token}
response = requests.put(plex_url)
$response = Invoke-RestMethod 'http://{ip_address}:32400/library/metadata/{id}/match?guid={guid}&name={name}&year={year}&{tracks}&X-Plex-Token={plex_token}' -Method 'PUT'
Write-Output $response