Download Media File
This API request will download, in full, a media file from the Plex server to the local machine. From Plex, the download won't appear as an offline media source. This will allow you to download and play the file outside of Plex.
The following can be downloaded from Plex: movies, TV shows, music tracks, photos, and other videos.
Entire TV seasons or music artists/albums cannot be downloaded using this API command.
URL
GET http://{ip_address}:32400/{part_path}?download={download}&X-Plex-Token={plex_token}Parameters
| Name | Description |
|---|---|
| ip_address | The IP address of the Plex Media server. |
| plex_token | The Plex token. |
| part_path | The internal path to the file that you would like to download. See Remarks below for more information on getting the path. |
| download | A flag indicating if the original file name is to be used as the name of the downloaded file. See Remarks below for more information. Valid values: 0 or 1. |
Return Status
| HTTP Code | Description |
|---|---|
| 200 | Success - The request was successful. |
| 401 | Unauthorized - The Plex token provided was not valid. |
| 403 | Forbidden - The Plex token does not have permission to download the file. |
Response
No response is returned except for the binary data of the media file. If you call this command from a Web browser, you will see the file download from the Web browser.
Remarks
There are several things to keep in mind when downloading a media file from Plex using this API.
Permissions
There could be permission restrictions associated with the user that will prevent the user from downloading a file.
These restrictions include:
- The user must have the Allow Downloads restriction enabled on their account on the Plex server.
- Users can only download media files that they can access from within Plex. For example, if they are restricted to movies with 'G' rating, they can only download movies with a 'G' rating.
If a user tries to download a media file they do not have access to, they will get a 403 status code.
A device token will work when downloading media files.
Part path parameter
The Part Path parameter used in the request is created internally by Plex. You can get the path by making additional API requests:
| Media Type | API Command | Part Path | Physical File Path |
|---|---|---|---|
| Movies | Get All Movies | MediaContainer | MediaContainer |
| TV Shows | Get All TV Show Episodes | MediaContainer | MediaContainer |
| Music Tracks | Get All Tracks for a Music Album | MediaContainer | MediaContainer |
You would use the value of the Part.key attribute from each of the above API requests as the value for the Part Path parameter in the download request.
You can rename a file by changing the file name part of the Part Path parameter in the request.
Download parameter
The Download parameter specifies whether the original file name for the media file is to be used, or the one specified in the request. If no file name is specified, then a random name will be used.
If a random name is used, then the extension of the download file will match the extension of the original media file.
The values of the download parameter are:
| Value | Description |
|---|---|
| 0 | Use the file name specified in the request as the name of the downloaded file. If a file name was not specified, then a random name will be used for the downloaded file. |
| 1 | The original file name will be used. If a file name was specified in the request, the original name will still be used. |
Only the file name, with the extension, will need to be specified in the request. Try to use the same extension as the original media file, which you can see by calling the API commands outlined Part path parameter section above. The full file path, along with the file name and extension, will be returned in the attribute listed in the Physical File Path column.
Examples
curl -X GET http://{ip_address}:32400/{part_path}?download={download}&X-Plex-Token={plex_token}
import requests
plex_url = http://{ip_address}:32400/{part_path}?download={download}&X-Plex-Token={plex_token}
response = requests.get(plex_url)
print(response.text)
$response = Invoke-RestMethod 'http://{ip_address}:32400/{part_path}?download={download}&X-Plex-Token={plex_token}' -Method 'GET'
Write-Output $response