mirror of
https://github.com/LukeHagar/plex-docs.git
synced 2025-12-06 04:20:40 +00:00
743 lines
25 KiB
YAML
743 lines
25 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Plex-API
|
|
summary: A Plex.TV API Map
|
|
description: An Open API Spec for interacting with Plex.tv
|
|
version: 0.0.3
|
|
contact:
|
|
name: Luke Hagar
|
|
url: 'https://www.LukeHagar.com'
|
|
email: Lukeslakemail@gmail.com
|
|
license:
|
|
name: MIT
|
|
identifier: MIT
|
|
servers:
|
|
- url: 'https://plex.tv/api/v2'
|
|
security:
|
|
- Token: []
|
|
ClientIdentifier: []
|
|
Device: []
|
|
DeviceName: []
|
|
Platform: []
|
|
PlatformVersion: []
|
|
Product: []
|
|
Version: []
|
|
components:
|
|
securitySchemes:
|
|
Token:
|
|
description: Plex Authentication Token
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Token
|
|
ClientIdentifier:
|
|
description: Plex Authentication Token
|
|
type: apiKey
|
|
in:
|
|
- header
|
|
- query
|
|
- cookie
|
|
name: X-Plex-Client-Identifier
|
|
DeviceName:
|
|
description: Primary name for the device eg. `Plex Web (Chrome)`
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Device-Name
|
|
Device:
|
|
description: |
|
|
The type of device your application is running on
|
|
Device name and or model number, eg `iPhone3,2`, `Motorola XOOM™`, `LG5200TV`
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Device
|
|
PlatformVersion:
|
|
description: |
|
|
Operating system version
|
|
eg `4.3.1`, `10.6.7`, `3.2`
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Platform-Version
|
|
Platform:
|
|
description: |
|
|
Platform name
|
|
eg: `Web`, `iOS`, `MacOSX`, `Android`, `LG`
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Platform
|
|
Product:
|
|
description: |
|
|
Plex application name
|
|
eg: `Laika`, `Plex Media Server`, `Media Link`
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Product
|
|
Version:
|
|
description: Plex application version number
|
|
type: apiKey
|
|
in: header
|
|
name: X-Plex-Version
|
|
paths:
|
|
/companions:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Companions Data
|
|
description: Get Companions Data
|
|
operationId: getCompanionsData
|
|
responses:
|
|
'200':
|
|
description: Companions Data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
identifier:
|
|
type: string
|
|
example: tv.plex.sonos
|
|
baseURL:
|
|
type: string
|
|
example: 'https://sonos.plex.tv'
|
|
title:
|
|
type: string
|
|
example: Sonos
|
|
linkURL:
|
|
type: string
|
|
example: 'https://sonos.plex.tv/link'
|
|
provides:
|
|
type: string
|
|
example: clientplayer
|
|
token:
|
|
type: string
|
|
example: VFnxitsRFdWx_WrzsKL
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/geoip:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Geo Data
|
|
description: Get Geo Data
|
|
operationId: getGeoData
|
|
responses:
|
|
'200':
|
|
description: Geo Data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: number
|
|
example: 1841489
|
|
name:
|
|
type: string
|
|
example: Blindkitty38's home
|
|
guestUserID:
|
|
type: number
|
|
example: 58815432
|
|
guestUserUUID:
|
|
type: string
|
|
example: f3df4e01bfca0787
|
|
guestEnabled:
|
|
type: boolean
|
|
subscription:
|
|
type: boolean
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/home:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Home Data
|
|
description: Get Home Data
|
|
operationId: getHomeData
|
|
responses:
|
|
'200':
|
|
description: Home Data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: number
|
|
example: 1841489
|
|
name:
|
|
type: string
|
|
example: Blindkitty38's home
|
|
guestUserID:
|
|
type: number
|
|
example: 58815432
|
|
guestUserUUID:
|
|
type: string
|
|
example: f3df4e01bfca0787
|
|
guestEnabled:
|
|
type: boolean
|
|
subscription:
|
|
type: boolean
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/pins:
|
|
post:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get a Pin
|
|
operationId: getPin
|
|
description: Retrieve a Pin from Plex.tv for authentication flows
|
|
security:
|
|
- ClientIdentifier: []
|
|
parameters:
|
|
- name: strong
|
|
description: |
|
|
Determines the kind of code returned by the API call
|
|
Strong codes are used for Pin authentication flows
|
|
Non-Strong codes are used for `Plex.tv/link`
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
required: false
|
|
responses:
|
|
'200':
|
|
description: The Pin
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
description: PinID for use with authentication
|
|
type: number
|
|
example: 1272322473
|
|
code:
|
|
type: string
|
|
example: 3patfx1a78ukcbr7x0n9bl26t
|
|
product:
|
|
type: string
|
|
example: Plex Web
|
|
trusted:
|
|
type: boolean
|
|
qr:
|
|
description: |
|
|
a link to a QR code hosted on plex.tv
|
|
The QR code redirects to the relevant `plex.tv/link` authentication page
|
|
Which then prompts the user for the 4 Digit Link Pin
|
|
type: string
|
|
example: 'https://plex.tv/api/v2/pins/qr/3patfx1a78ukcbr7x0n9bl26t'
|
|
clientIdentifier:
|
|
type: string
|
|
example: Postman
|
|
location:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
example: US
|
|
european_union_member:
|
|
type: boolean
|
|
continent_code:
|
|
type: string
|
|
example: NA
|
|
country:
|
|
type: string
|
|
example: United States
|
|
city:
|
|
type: string
|
|
example: Austin
|
|
time_zone:
|
|
type: string
|
|
example: America/Chicago
|
|
postal_code:
|
|
type: number
|
|
example: 78732
|
|
in_privacy_restricted_country:
|
|
type: boolean
|
|
subdivisions:
|
|
type: string
|
|
example: Texas
|
|
coordinates:
|
|
type: string
|
|
example: 30.3768 -97.8935
|
|
expiresIn:
|
|
type: number
|
|
example: 1800
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
example: 2023-04-12T17:00:03.000Z
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
example: 2023-04-12T17:30:03.000Z
|
|
authToken:
|
|
type: string
|
|
format: nullable
|
|
newRegistration:
|
|
type: string
|
|
format: nullable
|
|
'400':
|
|
description: X-Plex-Client-Identifier is missing
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1000
|
|
message:
|
|
type: string
|
|
example: X-Plex-Client-Identifier is missing
|
|
status:
|
|
type: number
|
|
example: 400
|
|
'/pins/{pinID}':
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Access Token
|
|
operationId: getToken
|
|
description: Retrieve an Access Token from Plex.tv after the Pin has already been authenticated
|
|
security:
|
|
- ClientIdentifier: []
|
|
parameters:
|
|
- name: pinID
|
|
description: The PinID to retrieve an access token for
|
|
in: path
|
|
schema:
|
|
type: string
|
|
required: true
|
|
responses:
|
|
'200':
|
|
description: Access Token
|
|
'400':
|
|
description: X-Plex-Client-Identifier is missing
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1000
|
|
message:
|
|
type: string
|
|
example: X-Plex-Client-Identifier is missing
|
|
status:
|
|
type: number
|
|
example: 400
|
|
/resources:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Devices
|
|
description: Get Devices
|
|
operationId: getDevices
|
|
parameters:
|
|
- name: includeHttps
|
|
description: Include Https entries in the results
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- name: includeRelay
|
|
description: Include Relay addresses in the results
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 0
|
|
- 1
|
|
- name: includeIPv6
|
|
description: Include IPv6 entries in the results
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
enum:
|
|
- 0
|
|
- 1
|
|
responses:
|
|
'200':
|
|
description: List of Plex Devices
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: Hera
|
|
product:
|
|
type: string
|
|
example: Plex Media Server
|
|
productVersion:
|
|
type: string
|
|
example: 1.31.3.6868-28fc46b27
|
|
platform:
|
|
type: string
|
|
example: Linux
|
|
platformVersion:
|
|
type: string
|
|
example: '5.19.17-Unraid (#2 SMP PREEMPT_DYNAMIC Wed Nov 2 11:54:15 PDT 2022)'
|
|
device:
|
|
type: string
|
|
example: PC
|
|
clientIdentifier:
|
|
type: string
|
|
example: 96f2fe7a78c9dc1f16a16bedbe90f98149be16b4
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
example: 2022-06-02T00:54:26.000Z
|
|
lastSeenAt:
|
|
type: string
|
|
format: date-time
|
|
example: 2023-04-11T05:53:59.000Z
|
|
provides:
|
|
type: string
|
|
example: server
|
|
ownerId:
|
|
type: string
|
|
format: nullable
|
|
sourceTitle:
|
|
type: string
|
|
format: nullable
|
|
publicAddress:
|
|
type: string
|
|
example: 68.248.140.20
|
|
accessToken:
|
|
type: string
|
|
example: CR3nxzsaSHdWx_WwZsJL
|
|
owned:
|
|
type: boolean
|
|
home:
|
|
type: boolean
|
|
synced:
|
|
type: boolean
|
|
relay:
|
|
type: boolean
|
|
presence:
|
|
type: boolean
|
|
httpsRequired:
|
|
type: boolean
|
|
publicAddressMatches:
|
|
type: boolean
|
|
dnsRebindingProtection:
|
|
type: boolean
|
|
natLoopbackSupported:
|
|
type: boolean
|
|
connections:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
protocol:
|
|
type: string
|
|
example: http
|
|
address:
|
|
type: string
|
|
example: 172.18.0.1
|
|
port:
|
|
type: number
|
|
example: 32400
|
|
uri:
|
|
type: string
|
|
example: 'http://172.18.0.1:32400'
|
|
local:
|
|
type: boolean
|
|
relay:
|
|
type: boolean
|
|
IPv6:
|
|
type: boolean
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/user:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get Logged in User
|
|
description: Get Logged in User
|
|
operationId: getUserDetails
|
|
responses:
|
|
'200':
|
|
description: Logged in user details
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/user/settings:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get User Settings
|
|
description: Get User Settings
|
|
operationId: getUserSettings
|
|
responses:
|
|
'200':
|
|
description: User Settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: experience
|
|
type:
|
|
type: string
|
|
example: json
|
|
value:
|
|
type: string
|
|
hidden:
|
|
type: boolean
|
|
updatedAt:
|
|
type: number
|
|
example: 1681769995
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
/user/settings/opt_outs:
|
|
get:
|
|
tags:
|
|
- Plex.tv
|
|
summary: Get User Opt Out Settings
|
|
description: Get User Opt Out Settings
|
|
operationId: getUserOptOutSettings
|
|
responses:
|
|
'200':
|
|
description: User Opt Out Settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
tv.plex.provider.podcasts:
|
|
type: string
|
|
example: opt_in
|
|
tv.plex.provider.news:
|
|
type: string
|
|
example: opt_in
|
|
tv.plex.provider.webshows:
|
|
type: string
|
|
example: opt_out
|
|
tv.plex.provider.music:
|
|
type: string
|
|
example: opt_out
|
|
tv.plex.provider.vod:
|
|
type: string
|
|
example: opt_in
|
|
scrobbling:
|
|
type: string
|
|
example: opt_in
|
|
'400':
|
|
description: 'Bad Request - A parameter was not specified, or was specified incorrectly.'
|
|
'401':
|
|
description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: number
|
|
example: 1001
|
|
message:
|
|
type: string
|
|
example: User could not be authenticated
|
|
status:
|
|
type: number
|
|
example: 401
|
|
tags:
|
|
- name: Activities
|
|
description: |
|
|
Activities are awesome. They provide a way to monitor and control asynchronous operations on the server. In order to receive real-time updates for activities, a client would normally subscribe via either EventSource or Websocket endpoints.
|
|
Activities are associated with HTTP replies via a special `X-Plex-Activity` header which contains the UUID of the activity.
|
|
Activities are optional cancellable. If cancellable, they may be cancelled via the `DELETE` endpoint. Other details:
|
|
- They can contain a `progress` (from 0 to 100) marking the percent completion of the activity.
|
|
- They must contain an `type` which is used by clients to distinguish the specific activity.
|
|
- They may contain a `Context` object with attributes which associate the activity with various specific entities (items, libraries, etc.)
|
|
- The may contain a `Response` object which attributes which represent the result of the asynchronous operation.
|
|
- name: Authentication
|
|
description: |
|
|
API Calls regarding authentication for Plex Media Server
|
|
- name: Butler
|
|
description: |
|
|
Butler is the task manager of the Plex Media Server Ecosystem.
|
|
- name: Server
|
|
description: |
|
|
Operations against the Plex Media Server System.
|
|
- name: Updater
|
|
description: |
|
|
This describes the API for searching and applying updates to the Plex Media Server.
|
|
Updates to the status can be observed via the Event API.
|
|
- name: Log
|
|
description: |
|
|
Submit logs to the Log Handler for Plex Media Server
|
|
- name: Security
|
|
description: |
|
|
API Calls against Security for Plex Media Server
|
|
- name: Library
|
|
description: |
|
|
API Calls interacting with Plex Media Server Libraries
|
|
- name: Hubs
|
|
description: |
|
|
Hubs are a structured two-dimensional container for media, generally represented by multiple horizontal rows.
|
|
- name: Playlists
|
|
description: |
|
|
Playlists are ordered collections of media. They can be dumb (just a list of media) or smart (based on a media query, such as "all albums from 2017").
|
|
They can be organized in (optionally nesting) folders.
|
|
Retrieving a playlist, or its items, will trigger a refresh of its metadata.
|
|
This may cause the duration and number of items to change.
|
|
- name: Search
|
|
description: |
|
|
API Calls that perform search operations with Plex Media Server
|
|
- name: User
|
|
description: |
|
|
API Calls that perform operations with Plex Media Server Users
|