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]/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.

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