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.
URL
PUT http://{ip_address}:32400/library/metadata/{id}/match?guid={guid}&name={name}&year={year}&{tracks}&X-Plex-Token={plex_token}Parameters
| Name | Description |
|---|---|
| ip_address | The IP address of the Plex Media server. |
| plex_token | The Plex token. |
| id | The 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. |
| guid | This 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. |
| name | The name of the album. |
| year | The year the album was released. |
| tracks | See the remarks below. |
Return Status
| HTTP Code | Description |
|---|---|
| 200 | Success - The request was successful. |
| 401 | Unauthorized - The Plex token provided was not valid. |
| 404 | Not Found - The Music Album ID value is incorrect. |
Response
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.
| Attribute | Description |
|---|---|
| size | The number of music albums. |
| identifier | The type of item. |
| mediaTagPrefix | Prefix for the media tag. |
| mediaTagVersion | Media tag version. Note: This could be a date and time value. |
Remarks
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.
Examples
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)
print(response.text)
$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