Update a Movie

Buy me a coffee

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/{library_id}/all?type=1&id={movie_id}&includeExternalMedia={include_external_media}&{parameter_values}&X-Plex-Token={plex_token}

Parameters

Name	Description
ip_address	The IP address of the Plex Media server.
plex_token	The Plex token.
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.
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

curl -X PUT http://{ip_address}:32400/library/sections/{library_id}/all?type=1&id={movie_id}&includeExternalMedia={include_external_media}&{parameter_values}&X-Plex-Token={plex_token}

import requests
plex_url = http://{ip_address}:32400/library/sections/{library_id}/all?type=1&id={movie_id}&includeExternalMedia={include_external_media}&{parameter_values}&X-Plex-Token={plex_token}
response = requests.put(plex_url)
print(response.text)

$response = Invoke-RestMethod 'http://{ip_address}:32400/library/sections/{library_id}/all?type=1&id={movie_id}&includeExternalMedia={include_external_media}&{parameter_values}&X-Plex-Token={plex_token}' -Method 'PUT'
Write-Output $response

Script examples

Below are a list of post and articles that provide an example that use this API endpoint:

How to Stop Plex from Changing Movie Posters

Buy me a coffee