Update Movie Details
The movie metadata can be updated from the Plex API. This can be useful if you wish to perform a bulk update to movies in a library.
URL
PUT http://[IP address]:32400/library/sections/[Movies Library ID]/all?type=1&id=[Movie ID]&includeExternalMedia=[Include External Media]&[Update Parameter Values]&X-Plex-Token=[PlexToken]
Parameters
Name | Description |
---|---|
IP address | The IP address of the Plex Media server. |
PlexToken | The temporary authentication Plex token. |
Movies Library ID | The key associated with a movies library. This key can be found by calling the Libraries API command and looking for a movies library. |
Movie ID | The key associated with the movie to be updated. This key can be found by calling the Get All Movies API command and looking for the movie to be updated. |
Include External Media | Flag indicating whether external media will be included. Set this to 1 to keep the update command the same as the way it is executed from the Web app. Valid values are 0 and 1. |
Update Parameter Values | A list of fields to be updated along with their values. The list of values is listed in the fields section below. |
Return Status
HTTP Code | Description |
---|---|
200 | Success - The request was successful. |
400 | Bad Request - A field name is not valid. |
401 | Unauthorized - The Plex token provided was not valid. |
500 | Internal Server Error - Field data is not valid. |
Response
There is no response returned by the server. Check the return status code to determine success.
Fields
The list of valid movie fields that can be updated using the Plex API is listed below.
Field Name | Parameter Name | Data Type | Notes |
---|---|---|---|
Title | title | string | |
Sort Title | sortTitle | string | |
Original Title | originalTitle | string | |
Edition | editionTitle | string | |
Originally Available | originallyAvailableAt | date | Format: yyyy-mm-dd |
Content Rating | contentRating | string | |
Rating | userRating | integer | Each star equals 2 (rounded up for odds). 1 star = 1 or 2, 2 stars = 3 or 4, etc. |
Studio | studio | string | |
Tagline | tagline | string | |
Summary | summary | string | |
Directors | director[index] | array | |
Country | country[index] | array | |
Genres | genre[index] | array | |
Writers | writer[index] | array | |
Producers | producer[index] | array | |
Collections | collection[index] | array | |
Labels | label[index] | array |
Non-array data types
For string
, integer
, and date
data types, you would update the value of those fields using the following structure:
[field name].value=[value]
For example, to update the title of a media item to "The Title of the Item", you would use the following (%20 is an encoded space character):
title.value=The%20Title%20of%20the%20Item
If you would like to clear out the value of a field, you just set it to nothing:
title.value=
Array data types
To specify the parameters to update a field that has a data type of array, you would use the information outlined in the Arrays documentation.
Locking a field
If you have edited the details of a media item from the Plex Web app, you will have noticed that you can lock the value of a field. Locking a field prevents Plex from overwriting it with another value that it finds online
It is good practice to lock a field that you have changed using the API. To lock a field, you would use the following structure:
[field name].locked=1
The value "1" indicates the field is locked. Setting the value to "0" will unlock the field.
For example, the following will lock the "Title" field for an item:
title.locked=1
For fields that have an array data type, you don't specify the index of the array, you only use the field name:
genre.locked=1
Examples
Example 1
Update the title of a movie with ID 286253 on the Plex Media Server located at the IP address of 192.168.1.4 to 'A Great Movie':
PUT http://192.168.1.4:32400/library/sections/14/all?type=1&id=286253&includeExternalMedia=1&title.value=A%20Great%20Movie&title.locked=1&X-Plex-Token=L6vkd7JtLHjsH5987vYY
Example 2
Update the 'Originally Available' date field to February 6, 2023 for a movie with ID 28454:
PUT http://192.168.1.4:32400/library/sections/14/all?type=1&id=286253&includeExternalMedia=1&originallyAvailableAt.value=2023-02-06&originallyAvailableAt.locked=1&X-Plex-Token=L6vkd7JtLHjsH5987vYY
Example 3
Added 'Action' to the genre for a movie with ID 28234:
PUT http://192.168.1.4:32400/library/sections/14/all?type=1&id=286253&includeExternalMedia=1&genre%5B0%5D.tag.tag=Action&genre.locked=1&X-Plex-Token=L6vkd7JtLHjsH5987vYY
Example 4
Clear the sort title for a movie with ID 15302, and unlock the field:
PUT http://192.168.1.4:32400/library/sections/14/all?type=1&id=286253&includeExternalMedia=1&sortTitle.value=&sortTitle.locked=0&X-Plex-Token=L6vkd7JtLHjsH5987vYY
Example 5
Remove 'Action' and 'Drama' from the genre for a movie with ID 28234, but keep the field locked:
PUT http://192.168.1.4:32400/library/sections/14/all?type=1&id=286253&includeExternalMedia=1&genre%5B%5D.tag.tag-=Action%2CDrama&genre.locked=1&X-Plex-Token=L6vkd7JtLHjsH5987vYY