-
Notifications
You must be signed in to change notification settings - Fork 39
Plex Web API Overview
dkay0670 edited this page Aug 2, 2022
·
17 revisions
All API information comes wrapped in the root node of
<MediaContainer></MediaContainer>The MediaContainer node can have many attributes and child nodes depending on the API's URL you are accessing.
All timestamps in the API are in Epoch time. See http://www.epochconverter.com/
The API is roughly RESTful in nature, and the server can return XML or JSON responses (see headers).
Base URL: http://IP:PORT/
| Call | URL | Description |
|---|---|---|
| Get | / | Transcode bitrateinfo, myPlexauthentication info |
| Get | /status/sessions | This will retrieve the "Now Playing" Information of the PMS. |
| Get | /status/sessions/history/all | Retrieves a listing of all history views. |
| Get | /search?query=string
|
This will search the database for the string provided. |
| Get | /library/sections | Contains all of the sections on the PMS. Confusingly, Plex's UI calls a section a library: e.g. "TV shows" or "Movies". This acts as a directory and you are able to "walk" through it. |
| Get | /library/sections/section ID/refresh |
Refreshes the library for the section passed in. |
| Get | /:/prefs | Gets the server preferences |
| Get | /servers | get the local List of servers |
| Delete | /library/sections/section ID/ |
Delete a section |
| Get | /library/onDeck | Show ondeck list |
| Get | photo/:/transcode?url=path to image&width=width&height=height
|
Get photo of specified height and width |
| GET | /myplex/account | Get Plex.TV account information |
| Get | /system | General plex system information |
| Get | /system/agents | Agents available (and some of their configuration) |
| Get | /:/scrobble?key=item rating key&identifier=com.plexapp.plugins.library |
Marks item with the corresponding rating key as watched. Use /:/unscrobble... to mark unwatched. |
| Get | /:/progress?key=item rating key&time=offset&identifier=com.plexapp.plugins.library |
Marks media item with the corresponding rating key as partially watched, populating its viewOffset field. Time is in milliseconds. |
| Get | /video/:/transcode/universal/decision?path=path to video&protocol=eg http&hasMDE=1 |
Ask the server whether it can provide the video with/without transcoding (based on the client profile) |
| Parameter | Value |
|---|---|
| X-Plex-Platform | (Platform name, eg iOS, MacOSX, Android, LG, etc) |
| X-Plex-Platform-Version | (Operating system version, eg 4.3.1, 10.6.7, 3.2) |
| X-Plex-Provides | (one or more of [player, controller, server]) |
| X-Plex-Client-Identifier | (UUID, serial number, or other number unique per device) |
| X-Plex-Product | (Plex application name, eg Laika, Plex Media Server, Media Link) |
| X-Plex-Version | (Plex application version number) |
| X-Plex-Device | (Device name and model number, eg iPhone3,2, Motorola XOOM™, LG5200TV) |
| X-Plex-Container-Size | (Paging Size, eg Plex-Container-Size=1) |
| X-Plex-Container-Start | (Paging Start, eg X-Plex-Container-Start=0) |
| X-Plex-Token | (Authentication token) |
| Header | Value |
|---|---|
| Accept | (application/json - sometimes not valid JSON - or application/xml) |
You can get a filtered view of any section by using the following endpoint:
GET /library/sections/X/all?<filters>
The filters are expressed via querystring parameters. Each parameter contains a field, operator and value(s). Valid operators are =, >=, <=, and !=. For tag-based fields (e.g. genre), only = and != operators are allowed, and correspond to “are tagged with” and “are not tagged with”.
-
year=2010⇢ returns all media from the year 2010 -
year>=1990⇢ returns all media from years 1990 and later. -
year!=2012⇢ returns all media from years other than 2012. -
year=2012,2013,2015⇢ returns all media from years 2012, 2013, and 2015.
When multiple parameters are passed, they are logically ANDed together.
-
year=2010&rating>=5⇢ all media from the year 2012 with a 5 or greater.
You can get a list of alphanumeric characters to display by using the following endpoint:
GET /library/sections/X/firstCharacter
You can then use the provided keys to return media items for that character.
GET /library/sections/X/firstCharacter/Y
It’s possible to obtain a list of the current transcode sessions:
GET /transcode/sessions
Given a session key, you can kill a transcode session with the following endpoint:
DELETE /transcode/sessions/<key>
When connecting to a remote server, you might need to know what token to send it; if you don’t know the machine identifier of the remote server, that’s hard, so there is an endpoint you can hit which returns basic information about the server, and isn’t protected.
GET /identity
<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="0" machineIdentifier="567-456-457" version="0.9.7.3-36679df" />| Type | URL | Example |
|---|---|---|
| GET | / | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /clients | ?X-Plex-Platform=<val> |
| GET | /status/sessions | |
| GET | /system/appstore/history | ?X-Plex-Container-Size=<val>&X-Plex-Container-Start=<val> |
| GET | /:/prefs | |
| GET | /servers | |
| GET | /library/sections | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/onDeck | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/recentlyAdded | ?X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&unwatched=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Client-Platform=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /channels/recentlyViewed | ?X-Plex-Container-Size=<val>&X-Plex-Container-Start=<val> |
| GET | /channels/all | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /sync/transcodeQueue | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| OPTIONS | / | |
| GET | /library/sections//filters | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/sections//sorts | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/sections/ | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/sections//firstCharacter | ?X-Plex-Platform=<val>&X-Plex-Token=<val>&X-Plex-Model=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/sections//all | ?X-Plex-Container-Size=<val>&X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device-Name=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Container-Start=<val>&X-Plex-Version=<val> |
| GET | /photo/:/transcode | ?X-Plex-Client-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&url=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Platform=<val>&height=<val>&X-Plex-Device=<val>&width=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| POST | /playQueues | ?shuffle=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&continuous=<val>&uri=<val>&X-Plex-Platform=<val>&X-Plex-Device=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&type=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /library/metadata/ | ?X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&checkFiles=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Platform-Version=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /:/timeline | ?X-Plex-Platform=<val>&playQueueItemID=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&ratingKey=<val>&X-Plex-Device=<val>&X-Plex-Username=<val>&state=<val>&X-Plex-Product=<val>&key=<val>&time=<val>&duration=<val>&X-Plex-Model=<val>&identifier=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /video/:/transcode/universal/ping | ?X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&session=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /video/:/transcode/universal/start.m3u8 | ?maxVideoBitrate=<val>&videoQuality=<val>&X-Plex-Platform=<val>&session=<val>&protocol=<val>&videoResolution=<val>&X-Plex-Device-Name=<val>&X-Plex-Model=<val>&directPlay=<val>&fastSeek=<val>&X-Plex-Device=<val>&subtitleSize=<val>&X-Plex-Platform-Version=<val>&X-Plex-Product=<val>&X-Plex-Client-Platform=<val>&X-Plex-Username=<val>&path=<val>&directStream=<val>&X-Plex-Token=<val>&audioBoost=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Version=<val> |
| GET | /library/metadata/ | ?X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&checkFiles=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&X-Plex-Platform-Version=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |
| GET | /video/:/transcode/universal/stop | ?X-Plex-Platform=<val>&X-Plex-Model=<val>&X-Plex-Token=<val>&X-Plex-Platform-Version=<val>&X-Plex-Client-Platform=<val>&X-Plex-Client-Identifier=<val>&X-Plex-Device=<val>&session=<val>&X-Plex-Product=<val>&X-Plex-Username=<val>&X-Plex-Device-Name=<val>&X-Plex-Version=<val> |