LukeParke/plex-docs
1
0
Fork 0
mirror of https://github.com/LukeHagar/plex-docs.git synced 2025-12-06 04:20:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
fbae5818429fb2f53dee3779a014e717bfcfadae
plex-docs/static/plex-media-server-spec-dereferenced.yaml
lukehagar fbae581842 Updating PMS Spec
2024-02-05 15:38:04 +00:00

9351 lines
414 KiB
YAML
Raw Blame History

openapi: 3.1.0
info:
title: Plex-API
summary: A Plex Media Server API Map
description: An Open API Spec for interacting with Plex.tv and Plex Servers
version: 0.0.3
contact:
name: Luke Hagar
url: 'https://www.LukeHagar.com'
email: Lukeslakemail@gmail.com
license:
name: MIT
identifier: MIT
servers:
- url: '{protocol}://{ip}:{port}'
description: The full address of your Plex Server
variables:
protocol:
default: http
description: The protocol to use when connecting to your plex server.
enum:
- http
- https
ip:
default: 10.10.10.47
description: The Local IP Address of your plex server.
port:
default: '32400'
description: The port to access your plex server.
security:
- accessToken: []
components:
securitySchemes:
accessToken:
description: Plex Authentication Token
type: apiKey
in: header
name: X-Plex-Token
paths:
/:
get:
tags:
- Server
summary: Server Capabilities
description: Server Capabilities
operationId: getServerCapabilities
responses:
'200':
description: The Server Capabilities
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
allowCameraUpload:
type: boolean
allowChannelAccess:
type: boolean
allowMediaDeletion:
type: boolean
allowSharing:
type: boolean
allowSync:
type: boolean
allowTuners:
type: boolean
backgroundProcessing:
type: boolean
certificate:
type: boolean
companionProxy:
type: boolean
countryCode:
type: string
diagnostics:
type: string
eventStream:
type: boolean
friendlyName:
type: string
hubSearch:
type: boolean
itemClusters:
type: boolean
livetv:
type: number
machineIdentifier:
type: string
mediaProviders:
type: boolean
multiuser:
type: boolean
musicAnalysis:
type: number
myPlex:
type: boolean
myPlexMappingState:
type: string
myPlexSigninState:
type: string
myPlexSubscription:
type: boolean
myPlexUsername:
type: string
offlineTranscode:
type: number
ownerFeatures:
type: string
photoAutoTag:
type: boolean
platform:
type: string
platformVersion:
type: string
pluginHost:
type: boolean
pushNotifications:
type: boolean
readOnlyLibraries:
type: boolean
streamingBrainABRVersion:
type: number
streamingBrainVersion:
type: number
sync:
type: boolean
transcoderActiveVideoSessions:
type: number
transcoderAudio:
type: boolean
transcoderLyrics:
type: boolean
transcoderPhoto:
type: boolean
transcoderSubtitles:
type: boolean
transcoderVideo:
type: boolean
transcoderVideoBitrates:
type: string
transcoderVideoQualities:
type: string
transcoderVideoResolutions:
type: string
updatedAt:
type: number
updater:
type: boolean
version:
type: string
voiceSearch:
type: boolean
Directory:
type: array
items:
type: object
properties:
count:
type: number
key:
type: string
title:
type: string
'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
'/:/prefs':
get:
tags:
- Server
summary: Get Server Preferences
description: Get Server Preferences
operationId: getServerPreferences
responses:
'200':
description: Server Preferences
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 161
Setting:
type: array
items:
oneOf:
- type: object
properties:
id:
type: string
example: FriendlyName
label:
type: string
example: Friendly name
summary:
type: string
example: 'This name will be used to identify this media server to other computers on your network. If you leave it blank, your computer''s name will be used instead.'
type:
type: string
example: text
default:
type: string
example: ''
value:
type: string
example: Hera
hidden:
type: boolean
example: false
advanced:
type: boolean
example: false
group:
type: string
example: general
- type: object
properties:
id:
type: string
example: ScheduledLibraryUpdateInterval
label:
type: string
example: Library scan interval
summary:
type: string
example: ''
type:
type: string
example: int
default:
type: integer
format: int32
example: 3600
value:
type: integer
format: int32
example: 3600
hidden:
type: boolean
example: false
advanced:
type: boolean
example: false
group:
type: string
example: library
enumValues:
type: string
example: '900:every 15 minutes|1800:every 30 minutes|3600:hourly|7200:every 2 hours|21600:every 6 hours|43200:every 12 hours|86400:daily'
example:
- id: FriendlyName
label: Friendly name
summary: 'This name will be used to identify this media server to other computers on your network. If you leave it blank, your computer''s name will be used instead.'
type: text
default: ''
value: Hera
hidden: false
advanced: false
group: general
- id: ScheduledLibraryUpdateInterval
label: Library scan interval
summary: ''
type: int
default: 3600
value: 3600
hidden: false
advanced: false
group: library
enumValues: '900:every 15 minutes|1800:every 30 minutes|3600:hourly|7200:every 2 hours|21600:every 6 hours|43200:every 12 hours|86400:daily'
'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
'/:/scrobble':
get:
tags:
- Media
summary: Mark Media Played
description: This will mark the provided media key as Played.
operationId: markPlayed
parameters:
- name: key
description: The media key to mark as played
in: query
schema:
type: number
example: 59398
required: true
responses:
'200':
description: Media is marked Played
'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
'/:/unscrobble':
get:
tags:
- Media
summary: Mark Media Unplayed
description: This will mark the provided media key as Unplayed.
operationId: markUnplayed
parameters:
- name: key
description: The media key to mark as Unplayed
in: query
schema:
type: number
example: 59398
required: true
responses:
'200':
description: Media is marked Unplayed
'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
'/:/progress':
post:
tags:
- Media
summary: Update Media Play Progress
description: |
This API command can be used to update the play progress of a media item.
operationId: updatePlayProgress
parameters:
- name: key
description: the media key
in: query
schema:
type: string
required: true
- name: time
description: 'The time, in milliseconds, used to set the media playback progress.'
in: query
schema:
type: number
example: 90000
required: true
- name: state
description: The playback state of the media item.
in: query
schema:
type: string
example: played
required: true
responses:
'200':
description: Success - The request was successful.
'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
'/:/timeline':
get:
tags:
- Video
summary: Get the timeline for a media item
description: Get the timeline for a media item
operationId: getTimeline
parameters:
- name: ratingKey
description: The rating key of the media item
required: true
in: query
schema:
type: number
example: 23409
- name: key
description: The key of the media item to get the timeline for
required: true
in: query
schema:
type: string
example: /library/metadata/23409
- name: state
description: The state of the media item
required: true
in: query
schema:
type: string
enum:
- playing
- paused
- stopped
example: playing
- name: hasMDE
description: Whether the media item has MDE
required: true
in: query
schema:
type: number
example: 1
- name: time
description: The time of the media item
required: true
in: query
schema:
type: number
example: 2000
- name: duration
description: The duration of the media item
required: true
in: query
schema:
type: number
example: 10000
- name: context
description: The context of the media item
required: true
in: query
schema:
type: string
example: 'home:hub.continueWatching'
- name: playQueueItemID
description: The play queue item ID of the media item
required: true
in: query
schema:
type: number
example: 1
- name: playBackTime
description: The playback time of the media item
required: true
in: query
schema:
type: number
example: 2000
- name: row
description: The row of the media item
required: true
in: query
schema:
type: number
example: 1
responses:
'200':
description: The timeline for the media item
'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
/activities:
get:
tags:
- Activities
summary: Get Server Activities
description: Get Server Activities
operationId: getServerActivities
responses:
'200':
description: The Server Activities
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
Activity:
type: array
items:
type: object
properties:
uuid:
type: string
type:
type: string
cancellable:
type: boolean
userID:
type: number
title:
type: string
subtitle:
type: string
progress:
type: number
Context:
type: object
properties:
librarySectionID:
type: string
'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
'/activities/{activityUUID}':
delete:
tags:
- Activities
summary: Cancel Server Activities
description: Cancel Server Activities
operationId: cancelServerActivities
parameters:
- name: activityUUID
description: The UUID of the activity to cancel.
in: path
schema:
type: string
example: 25b71ed5-0f9d-461c-baa7-d404e9e10d3e
required: true
responses:
'200':
description: The Server Activity was canceled
'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
/butler:
get:
tags:
- Butler
summary: Get Butler tasks
description: Returns a list of butler tasks
operationId: getButlerTasks
responses:
'200':
description: All butler tasks
content:
application/json:
schema:
type: object
properties:
ButlerTasks:
type: object
properties:
ButlerTask:
type: array
items:
type: object
properties:
name:
type: string
example: BackupDatabase
interval:
type: number
example: 3
scheduleRandomized:
type: boolean
enabled:
type: boolean
title:
type: string
example: Backup Database
description:
type: string
example: Create a backup copy of the server's database in the configured backup directory
'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
post:
tags:
- Butler
summary: Start all Butler tasks
description: |
This endpoint will attempt to start all Butler tasks that are enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria:
1. Any tasks not scheduled to run on the current day will be skipped.
2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately.
3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window.
4. If we are outside the configured window, the task will start immediately.
operationId: startAllTasks
responses:
'200':
description: All tasks were started
'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
delete:
tags:
- Butler
summary: Stop all Butler tasks
description: |
This endpoint will stop all currently running tasks and remove any scheduled tasks from the queue.
operationId: stopAllTasks
responses:
'200':
description: All tasks were stopped
'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
'/butler/{taskName}':
post:
tags:
- Butler
summary: Start a single Butler task
description: |
This endpoint will attempt to start a single Butler task that is enabled in the settings. Butler tasks normally run automatically during a time window configured on the server's Settings page but can be manually started using this endpoint. Tasks will run with the following criteria:
1. Any tasks not scheduled to run on the current day will be skipped.
2. If a task is configured to run at a random time during the configured window and we are outside that window, the task will start immediately.
3. If a task is configured to run at a random time during the configured window and we are within that window, the task will be scheduled at a random time within the window.
4. If we are outside the configured window, the task will start immediately.
operationId: startTask
parameters:
- name: taskName
description: the name of the task to be started.
in: path
schema:
type: string
enum:
- BackupDatabase
- BuildGracenoteCollections
- CheckForUpdates
- CleanOldBundles
- CleanOldCacheFiles
- DeepMediaAnalysis
- GenerateAutoTags
- GenerateChapterThumbs
- GenerateMediaIndexFiles
- OptimizeDatabase
- RefreshLibraries
- RefreshLocalMedia
- RefreshPeriodicMetadata
- UpgradeMediaAnalysis
required: true
responses:
'200':
description: The task was started successfully
'202':
description: The task was already running.
'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
delete:
tags:
- Butler
summary: Stop a single Butler task
description: |
This endpoint will stop a currently running task by name, or remove it from the list of scheduled tasks if it exists. See the section above for a list of task names for this endpoint.
operationId: stopTask
parameters:
- name: taskName
description: The name of the task to be started.
in: path
schema:
type: string
enum:
- BackupDatabase
- BuildGracenoteCollections
- CheckForUpdates
- CleanOldBundles
- CleanOldCacheFiles
- DeepMediaAnalysis
- GenerateAutoTags
- GenerateChapterThumbs
- GenerateMediaIndexFiles
- OptimizeDatabase
- RefreshLibraries
- RefreshLocalMedia
- RefreshPeriodicMetadata
- UpgradeMediaAnalysis
required: true
responses:
'200':
description: The task was stopped
'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
'404':
description: The task was not running
/clients:
get:
tags:
- Server
summary: Get Available Clients
description: Get Available Clients
operationId: getAvailableClients
responses:
'200':
description: Available Clients
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 1
Server:
type: array
items:
type: object
properties:
name:
type: string
example: iPad
host:
type: string
example: 10.10.10.102
address:
type: string
example: 10.10.10.102
port:
type: number
example: 32500
machineIdentifier:
type: string
example: A2E901F8-E016-43A7-ADFB-EF8CA8A4AC05
version:
type: string
example: '8.17'
protocol:
type: string
example: plex
product:
type: string
example: Plex for iOS
deviceClass:
type: string
example: tablet
protocolVersion:
type: number
example: 2
protocolCapabilities:
type: string
example: 'playback,playqueues,timeline,provider-playback'
'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
/devices:
get:
tags:
- Server
summary: Get Devices
description: Get Devices
operationId: getDevices
responses:
'200':
description: Devices
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 151
identifier:
type: string
example: com.plexapp.system.devices
Device:
type: array
items:
type: object
properties:
id:
type: number
example: 1
name:
type: string
example: iPhone
platform:
type: string
example: iOS
clientIdentifier:
type: string
createdAt:
type: number
example: 1654131230
'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
/hubs:
get:
tags:
- Hubs
summary: Get Global Hubs
description: Get Global Hubs filtered by the parameters provided.
operationId: getGlobalHubs
parameters:
- name: count
description: The number of items to return with each hub.
in: query
schema:
type: number
required: false
- name: onlyTransient
description: 'Only return hubs which are "transient", meaning those which are prone to changing after media playback or addition (e.g. On Deck, or Recently Added).'
in: query
schema:
type: integer
enum:
- 0
- 1
required: false
responses:
'200':
description: returns global hubs
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 8
allowSync:
type: boolean
example: true
identifier:
type: string
example: com.plexapp.plugins.library
Hub:
type: array
items:
type: object
properties:
hubKey:
type: string
example: '/library/metadata/50768,65523,58188,57341,57302,57070'
key:
type: string
example: '/playlists/all?type=15&sort=lastViewedAt:desc&playlistType=video,audio'
title:
type: string
example: Recent Playlists
type:
type: string
example: playlist
hubIdentifier:
type: string
example: home.playlists
context:
type: string
example: hub.home.playlists
size:
type: integer
format: int32
example: 6
more:
type: boolean
example: true
style:
type: string
example: shelf
promoted:
type: boolean
example: true
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '57070'
key:
type: string
example: /playlists/57070/items
guid:
type: string
example: 'com.plexapp.agents.none://9fee6c5b-3143-4923-813e-57bd0190056c'
type:
type: string
example: playlist
title:
type: string
example: November Movie Day
titleSort:
type: string
example: Tracks
summary:
type: string
example: ''
smart:
type: boolean
example: false
playlistType:
type: string
example: video
composite:
type: string
example: /playlists/57070/composite/1668787730
icon:
type: string
example: 'playlist://image.smart'
viewCount:
type: integer
format: int32
example: 2
lastViewedAt:
type: integer
format: int32
example: 1668787732
duration:
type: integer
format: int32
example: 16873000
leafCount:
type: integer
format: int32
example: 3
addedAt:
type: integer
format: int32
example: 1668779618
updatedAt:
type: integer
format: int32
example: 1668787730
example:
- ratingKey: '57070'
key: /playlists/57070/items
guid: 'com.plexapp.agents.none://9fee6c5b-3143-4923-813e-57bd0190056c'
type: playlist
title: November Movie Day
titleSort: Tracks
summary: ''
smart: false
playlistType: video
composite: /playlists/57070/composite/1668787730
icon: 'playlist://image.smart'
viewCount: 2
lastViewedAt: 1668787732
duration: 16873000
leafCount: 3
addedAt: 1668779618
updatedAt: 1668787730
example:
- hubKey: '/library/metadata/50768,65523,58188,57341,57302,57070'
key: '/playlists/all?type=15&sort=lastViewedAt:desc&playlistType=video,audio'
title: Recent Playlists
type: playlist
hubIdentifier: home.playlists
context: hub.home.playlists
size: 6
more: true
style: shelf
promoted: true
Metadata:
- ratingKey: '50768'
key: /playlists/50768/items
guid: 'com.plexapp.agents.none://81658e0d-cd4e-4c73-abb9-832b2ae2037b'
type: playlist
title: ❤️ Tracks
titleSort: Tracks
summary: 'All your highly rated tracks, in one convenient place.'
smart: true
playlistType: audio
composite: /playlists/50768/composite/1704333758
icon: 'playlist://image.smart'
viewCount: 47
lastViewedAt: 1705329935
duration: 42864000
leafCount: 178
addedAt: 1655309388
updatedAt: 1704333758
- ratingKey: '65523'
key: /playlists/65523/items
guid: 'com.plexapp.agents.none://1bcdd596-892b-4856-9f28-b4338c439300'
type: playlist
title: Car Rides
summary: ''
smart: false
playlistType: audio
composite: /playlists/65523/composite/1698597932
viewCount: 2
lastViewedAt: 1698597949
duration: 4864000
leafCount: 19
addedAt: 1697993545
updatedAt: 1698597932
- ratingKey: '58188'
key: /playlists/58188/items
guid: 'com.plexapp.agents.none://8f0441d3-2a28-4644-a2f1-b7deeb290dff'
type: playlist
title: Workout
summary: ''
smart: false
playlistType: audio
composite: /playlists/58188/composite/1680825595
viewCount: 4
lastViewedAt: 1680825596
duration: 12522000
leafCount: 56
addedAt: 1679616785
updatedAt: 1680825595
- ratingKey: '57341'
key: /playlists/57341/items
guid: 'com.plexapp.agents.none://bf8778c3-20a3-4619-8eb0-3c172c18ffd6'
type: playlist
title: January Movie Day
summary: ''
smart: false
playlistType: video
composite: /playlists/57341/composite/1673372385
viewCount: 1
lastViewedAt: 1673372306
duration: 19119000
leafCount: 3
addedAt: 1673372306
updatedAt: 1673372385
- ratingKey: '57302'
key: /playlists/57302/items
guid: 'com.plexapp.agents.none://f25064ed-05bb-4bcf-b70c-ed7514b70929'
type: playlist
title: December Movie Day
summary: ''
smart: false
playlistType: video
composite: /playlists/57302/composite/1671205874
viewCount: 2
lastViewedAt: 1671206853
duration: 23040000
leafCount: 3
addedAt: 1671197078
updatedAt: 1671205874
- ratingKey: '57070'
key: /playlists/57070/items
guid: 'com.plexapp.agents.none://9fee6c5b-3143-4923-813e-57bd0190056c'
type: playlist
title: November Movie Day
summary: ''
smart: false
playlistType: video
composite: /playlists/57070/composite/1668787730
viewCount: 2
lastViewedAt: 1668787732
duration: 16873000
leafCount: 3
addedAt: 1668779618
updatedAt: 1668787730
'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
/hubs/search:
get:
tags:
- Search
summary: Perform a search
operationId: performSearch
description: |
This endpoint performs a search across all library sections, or a single section, and returns matches as hubs, split up by type. It performs spell checking, looks for partial matches, and orders the hubs based on quality of results. In addition, based on matches, it will return other related matches (e.g. for a genre match, it may return movies in that genre, or for an actor match, movies with that actor).
In the response's items, the following extra attributes are returned to further describe or disambiguate the result:
- `reason`: The reason for the result, if not because of a direct search term match; can be either:
- `section`: There are multiple identical results from different sections.
- `originalTitle`: There was a search term match from the original title field (sometimes those can be very different or in a foreign language).
- `<hub identifier>`: If the reason for the result is due to a result in another hub, the source hub identifier is returned. For example, if the search is for "dylan" then Bob Dylan may be returned as an artist result, an a few of his albums returned as album results with a reason code of `artist` (the identifier of that particular hub). Or if the search is for "arnold", there might be movie results returned with a reason of `actor`
- `reasonTitle`: The string associated with the reason code. For a section reason, it'll be the section name; For a hub identifier, it'll be a string associated with the match (e.g. `Arnold Schwarzenegger` for movies which were returned because the search was for "arnold").
- `reasonID`: The ID of the item associated with the reason for the result. This might be a section ID, a tag ID, an artist ID, or a show ID.
This request is intended to be very fast, and called as the user types.
parameters:
- name: query
description: The query term
in: query
schema:
type: string
examples:
- arnold
- dylan
required: true
- name: sectionId
description: 'This gives context to the search, and can result in re-ordering of search result hubs'
in: query
schema:
type: number
required: false
- name: limit
description: The number of items to return per hub
in: query
schema:
type: number
example: 5
default: 3
responses:
'200':
description: The search results
'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
/hubs/search/voice:
get:
tags:
- Search
summary: Perform a voice search
operationId: performVoiceSearch
description: |
This endpoint performs a search specifically tailored towards voice or other imprecise input which may work badly with the substring and spell-checking heuristics used by the `/hubs/search` endpoint.
It uses a [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) heuristic to search titles, and as such is much slower than the other search endpoint.
Whenever possible, clients should limit the search to the appropriate type.
Results, as well as their containing per-type hubs, contain a `distance` attribute which can be used to judge result quality.
parameters:
- name: query
description: The query term
in: query
schema:
type: string
examples:
- dead+poop
required: true
- name: sectionId
description: 'This gives context to the search, and can result in re-ordering of search result hubs'
in: query
schema:
type: number
required: false
- name: limit
description: The number of items to return per hub
in: query
schema:
type: number
example: 5
default: 3
required: false
responses:
'200':
description: The search results
'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
'/hubs/sections/{sectionId}':
get:
tags:
- Hubs
summary: Get library specific hubs
description: |
This endpoint will return a list of library specific hubs
operationId: getLibraryHubs
parameters:
- name: sectionId
description: the Id of the library to query
in: path
schema:
type: number
required: true
- name: count
description: The number of items to return with each hub.
in: query
schema:
type: number
required: false
- name: onlyTransient
description: 'Only return hubs which are "transient", meaning those which are prone to changing after media playback or addition (e.g. On Deck, or Recently Added).'
in: query
schema:
type: integer
enum:
- 0
- 1
required: false
responses:
'200':
description: The hubs specific to the library
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 7
allowSync:
type: boolean
example: true
identifier:
type: string
example: com.plexapp.plugins.library
librarySectionID:
type: integer
format: int32
example: 1
librarySectionTitle:
type: string
example: Movies
librarySectionUUID:
type: string
example: 322a231a-b7f7-49f5-920f-14c61199cd30
Hub:
type: array
items:
type: object
properties:
key:
type: string
example: '/library/sections/1/all?sort=lastViewedAt:desc&unwatched=0&viewOffset=0'
title:
type: string
example: Recently Played Movies
type:
type: string
example: movie
hubIdentifier:
type: string
example: movie.recentlyviewed.1
context:
type: string
example: hub.movie.recentlyviewed
size:
type: integer
format: int32
example: 6
more:
type: boolean
example: true
style:
type: string
example: shelf
hubKey:
type: string
example: '/library/metadata/66485,66098,57249,11449,5858,14944'
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '14944'
key:
type: string
example: /library/metadata/14944
guid:
type: string
example: 'plex://movie/5d77686eeb5d26001f1eb339'
studio:
type: string
example: Walt Disney Animation Studios
type:
type: string
example: movie
title:
type: string
example: Tangled
librarySectionTitle:
type: string
example: Movies
librarySectionID:
type: integer
format: int32
example: 1
librarySectionKey:
type: string
example: /library/sections/1
contentRating:
type: string
example: PG
summary:
type: string
example: 'The magically long-haired Rapunzel has spent her entire life in a tower, but now that a runaway thief has stumbled upon her, she is about to discover the world for the first time, and who she really is.'
rating:
type: number
example: 8.9
audienceRating:
type: number
example: 8.7
viewCount:
type: integer
format: int32
example: 1
lastViewedAt:
type: integer
format: int32
example: 1704936047
year:
type: integer
format: int32
example: 2010
tagline:
type: string
example: They're taking adventure to new lengths.
thumb:
type: string
example: /library/metadata/14944/thumb/1705739847
art:
type: string
example: /library/metadata/14944/art/1705739847
duration:
type: integer
format: int32
example: 6017237
originallyAvailableAt:
type: string
format: date
example: 2010-11-24T00:00:00.000Z
addedAt:
type: integer
format: int32
example: 1589412494
updatedAt:
type: integer
format: int32
example: 1705739847
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
primaryExtraKey:
type: string
example: /library/metadata/14952
ratingImage:
type: string
example: 'rottentomatoes://image.rating.ripe'
Media:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 38247
duration:
type: integer
format: int32
example: 6017237
bitrate:
type: integer
format: int32
example: 2051
width:
type: integer
format: int32
example: 1920
height:
type: integer
format: int32
example: 1080
aspectRatio:
type: number
example: 1.78
audioChannels:
type: integer
format: int32
example: 2
audioCodec:
type: string
example: aac
videoCodec:
type: string
example: h264
videoResolution:
type: string
example: '1080'
container:
type: string
example: mp4
videoFrameRate:
type: string
example: 24p
optimizedForStreaming:
type: integer
format: int32
example: 1
audioProfile:
type: string
example: lc
has64bitOffsets:
type: boolean
example: false
videoProfile:
type: string
example: high
Part:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 38247
key:
type: string
example: /library/parts/38247/1589412494/file.mp4
duration:
type: integer
format: int32
example: 6017237
file:
type: string
example: /movies/Tangled (2010)/Tangled (2010) Bluray-1080p.mp4
size:
type: integer
format: int32
example: 1545647447
audioProfile:
type: string
example: lc
container:
type: string
example: mp4
has64bitOffsets:
type: boolean
example: false
optimizedForStreaming:
type: boolean
example: true
videoProfile:
type: string
example: high
example:
- id: 38247
key: /library/parts/38247/1589412494/file.mp4
duration: 6017237
file: /movies/Tangled (2010)/Tangled (2010) Bluray-1080p.mp4
size: 1545647447
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
example:
- id: 38247
duration: 6017237
bitrate: 2051
width: 1920
height: 1080
aspectRatio: 1.78
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 38247
key: /library/parts/38247/1589412494/file.mp4
duration: 6017237
file: /movies/Tangled (2010)/Tangled (2010) Bluray-1080p.mp4
size: 1545647447
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
type: array
items:
type: object
properties:
tag:
type: string
example: Animation
example:
- tag: Animation
Country:
type: array
items:
type: object
properties:
tag:
type: string
example: United States of America
example:
- tag: United States of America
Director:
type: array
items:
type: object
properties:
tag:
type: string
example: Nathan Greno
example:
- tag: Nathan Greno
Role:
type: array
items:
type: object
properties:
tag:
type: string
example: Donna Murphy
example:
- tag: Donna Murphy
Writer:
type: array
items:
type: object
properties:
tag:
type: string
example: Wilhelm Grimm
example:
- tag: Wilhelm Grimm
skipCount:
type: integer
format: int32
example: 1
chapterSource:
type: string
example: media
example:
- ratingKey: '14944'
key: /library/metadata/14944
guid: 'plex://movie/5d77686eeb5d26001f1eb339'
studio: Walt Disney Animation Studios
type: movie
title: Tangled
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG
summary: 'The magically long-haired Rapunzel has spent her entire life in a tower, but now that a runaway thief has stumbled upon her, she is about to discover the world for the first time, and who she really is.'
rating: 8.9
audienceRating: 8.7
viewCount: 1
lastViewedAt: 1704936047
year: 2010
tagline: They're taking adventure to new lengths.
thumb: /library/metadata/14944/thumb/1705739847
art: /library/metadata/14944/art/1705739847
duration: 6017237
originallyAvailableAt: 2010-11-24T00:00:00.000Z
addedAt: 1589412494
updatedAt: 1705739847
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/14952
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 38247
duration: 6017237
bitrate: 2051
width: 1920
height: 1080
aspectRatio: 1.78
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 38247
key: /library/parts/38247/1589412494/file.mp4
duration: 6017237
file: /movies/Tangled (2010)/Tangled (2010) Bluray-1080p.mp4
size: 1545647447
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
- tag: Comedy
- tag: Animation
Country:
- tag: United States of America
Director:
- tag: Byron Howard
- tag: Nathan Greno
Role:
- tag: Mandy Moore
- tag: Zachary Levi
- tag: Donna Murphy
Writer:
- tag: Jacob Grimm
- tag: Wilhelm Grimm
skipCount: 1
chapterSource: media
promoted:
type: boolean
example: true
random:
type: boolean
example: true
example:
- key: '/library/sections/1/all?sort=lastViewedAt:desc&unwatched=0&viewOffset=0'
title: Recently Played Movies
type: movie
hubIdentifier: movie.recentlyviewed.1
context: hub.movie.recentlyviewed
size: 6
more: true
style: shelf
hubKey: '/library/metadata/66485,66098,57249,11449,5858,14944'
Metadata:
- ratingKey: '66485'
key: /library/metadata/66485
guid: 'plex://movie/5d776c3251dd69001fe38bb4'
studio: Termite Films
type: movie
title: Kedi
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: Not Rated
summary: 'A profile of an ancient city and its unique people, seen through the eyes of the most mysterious and beloved animal humans have ever known, the Cat.'
rating: 9.8
audienceRating: 8.5
viewCount: 2
lastViewedAt: 1705786111
year: 2017
tagline: 'A cat meowing at your feet, looking up at you, is life smiling at you...'
thumb: /library/metadata/66485/thumb/1702586907
art: /library/metadata/66485/art/1702586907
duration: 4736174
originallyAvailableAt: 2017-02-10T00:00:00.000Z
addedAt: 1702586905
updatedAt: 1702586907
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/66486
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 129531
duration: 4736174
bitrate: 2377
width: 1920
height: 1080
aspectRatio: 1.78
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 0
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 129778
key: /library/parts/129778/1702586883/file.mp4
duration: 4736174
file: /movies/Kedi (2017)/Kedi (2017) 1080p x264.mp4
size: 1410810905
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Genre:
- tag: Documentary
Country:
- tag: United States of America
Director:
- tag: Ceyda Torun
Role:
- tag: Bülent Üstün
- ratingKey: '66098'
key: /library/metadata/66098
guid: 'plex://movie/5d9f34f4adeb7a0021ce020f'
studio: Touchwood Pacific Partners 1
type: movie
title: 'Homeward Bound: The Incredible Journey'
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: G
summary: 'A fun-loving American bulldog pup, a hilarious Himalayan cat, and a wise old golden retriever embark on a long trek through the rugged wilderness of the Sierra Nevada mountains in a quest to reach home and their beloved owners.'
rating: 8.7
audienceRating: 7.1
viewCount: 2
lastViewedAt: 1705709811
year: 1993
tagline: 'In the classic tradition of Walt Disney Pictures comes a story about courage, adventure and friendship.'
thumb: /library/metadata/66098/thumb/1703148781
art: /library/metadata/66098/art/1703148781
duration: 5065775
originallyAvailableAt: 1993-02-12T00:00:00.000Z
addedAt: 1700434925
updatedAt: 1703148781
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/66099
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 129003
duration: 5065775
bitrate: 2444
width: 1904
height: 1024
aspectRatio: 1.85
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 129250
key: /library/parts/129250/1700434864/file.mp4
duration: 5065775
file: '/movies/Homeward Bound The Incredible Journey (1993)/Homeward Bound The Incredible Journey (1993) [BluRay] [1080p] [YTS.LT].mp4'
size: 1550855333
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
- tag: Adventure
- tag: Comedy
Country:
- tag: United States of America
Director:
- tag: Duwayne Dunham
Writer:
- tag: Caroline Thompson
- tag: Linda Woolverton
Role:
- tag: Michael J. Fox
- tag: Sally Field
- tag: Don Ameche
- ratingKey: '57249'
key: /library/metadata/57249
guid: 'plex://movie/60eff7d3e22797002c55c1cc'
studio: Nickelodeon Movies
type: movie
title: Blue's Big City Adventure
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: TV-Y
summary: 'Josh and Blue skidoo to New York City to audition for Rainbow Puppy''s Broadway musical, but they get lost when Josh accidentally left his Handy Dandy Notebook at home. This leads to a game of Blue''s Clues to figure out where the audition is. Meanwhile, Tickety Tock and her friends go to New York City to find Josh and Blue and get to the audition with help from Joe and Steve.'
rating: 8.3
audienceRating: 8.6
viewCount: 8
skipCount: 1
lastViewedAt: 1705681955
year: 2022
tagline: All They Need is You.
thumb: /library/metadata/57249/thumb/1704274800
art: /library/metadata/57249/art/1704274800
duration: 4459050
originallyAvailableAt: 2022-11-18T00:00:00.000Z
addedAt: 1669671356
updatedAt: 1704274800
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/57250
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 115470
duration: 4459050
bitrate: 6384
width: 3840
height: 2160
aspectRatio: 1.78
audioChannels: 6
audioCodec: aac
videoCodec: hevc
videoResolution: 4k
container: mkv
videoFrameRate: 24p
audioProfile: lc
videoProfile: main 10
Part:
- id: 115478
key: /library/parts/115478/1669671340/file.mkv
duration: 4459050
file: '/movies/Blue''s Big City Adventure (2022)/Blues.Big.City.Adventure.2022.2160p.4K.WEB.x265.10bit.AAC5.1-[YTS.MX].mkv'
size: 3560750664
audioProfile: lc
container: mkv
videoProfile: main 10
Genre:
- tag: Comedy
- tag: Family
Country:
- tag: Canada
- tag: Ireland
Director:
- tag: Matt Stawski
Writer:
- tag: Traci Paige Johnson
- tag: Todd Kessler
Role:
- tag: Joshua Dela Cruz
- tag: Steve Burns
- tag: Donovan Patton
- ratingKey: '11449'
key: /library/metadata/11449
guid: 'plex://movie/5d776edfad5437001f803cf9'
studio: Walt Disney Pictures
type: movie
title: Onward
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG
summary: 'In a magical world full of technological advances, elven brothers Ian and Barley Lightfoot set out on an adventure to resurrect their late father for a day.'
rating: 8.8
audienceRating: 9.5
viewCount: 3
lastViewedAt: 1705543126
year: 2020
tagline: Their quest begineth.
thumb: /library/metadata/11449/thumb/1705224000
art: /library/metadata/11449/art/1705224000
duration: 6141428
originallyAvailableAt: 2020-03-04T00:00:00.000Z
addedAt: 1589237130
updatedAt: 1705224000
audienceRatingImage: 'rottentomatoes://image.rating.upright'
chapterSource: media
primaryExtraKey: /library/metadata/11470
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 29291
duration: 6141428
bitrate: 10977
width: 1920
height: 804
aspectRatio: 2.35
audioChannels: 8
audioCodec: dca-ma
videoCodec: h264
videoResolution: '1080'
container: mkv
videoFrameRate: 24p
audioProfile: ma
videoProfile: high
Part:
- id: 29291
key: /library/parts/29291/1589237130/file.mkv
duration: 6141428
file: /movies/Onward (2020)/Onward (2020) Bluray-1080p.mkv
size: 8426669232
audioProfile: ma
container: mkv
videoProfile: high
- id: 29315
duration: 6142006
bitrate: 2639
width: 1920
height: 800
aspectRatio: 2.35
audioChannels: 6
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 29315
key: /library/parts/29315/1629002847/file.mp4
duration: 6142006
file: /movies/Onward (2020)/Onward (2020) WEBRip-1080p.mp4
size: 2026154995
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
- tag: Animation
- tag: Comedy
Country:
- tag: United States of America
Director:
- tag: Dan Scanlon
Writer:
- tag: Kelsey Mann
- tag: Dan Scanlon
Role:
- tag: Tom Holland
- tag: Chris Pratt
- tag: Julia Louis-Dreyfus
- ratingKey: '5858'
key: /library/metadata/5858
guid: 'plex://movie/5d776b85594b2b001e6dc641'
studio: Walt Disney Pictures
type: movie
title: Frozen II
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG
summary: 'Anna, Elsa, Kristoff, Olaf and Sven leave Arendelle to travel to an ancient, autumn-bound forest of an enchanted land. They set out to find the origin of Elsa''s powers in order to save their kingdom.'
rating: 7.7
audienceRating: 9.2
viewCount: 1
skipCount: 1
lastViewedAt: 1705337663
year: 2019
tagline: The past is not what it seems.
thumb: /library/metadata/5858/thumb/1704621922
art: /library/metadata/5858/art/1704621922
duration: 6194042
originallyAvailableAt: 2019-11-20T00:00:00.000Z
addedAt: 1588207762
updatedAt: 1704621922
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/5892
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 14954
duration: 6194042
bitrate: 2538
width: 1920
height: 800
aspectRatio: 2.35
audioChannels: 6
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 14954
key: /library/parts/14954/1588207762/file.mp4
duration: 6194042
file: /movies/Frozen II (2019)/Frozen II (2019) Bluray-1080p.mp4
size: 1969230037
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
- id: 14999
duration: 6244271
bitrate: 2536
width: 1920
height: 800
aspectRatio: 2.35
audioChannels: 6
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 14999
key: /library/parts/14999/1629001526/file.mp4
duration: 6244271
file: /movies/Frozen II (2019)/Frozen II (2019) WEBRip-1080p.mp4
size: 1983357282
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
- tag: Adventure
- tag: Animation
Country:
- tag: United States of America
Director:
- tag: Chris Buck
- tag: Jennifer Lee
Writer:
- tag: Chris Buck
- tag: Hans Christian Andersen
Role:
- tag: Idina Menzel
- tag: Kristen Bell
- tag: Josh Gad
- ratingKey: '14944'
key: /library/metadata/14944
guid: 'plex://movie/5d77686eeb5d26001f1eb339'
studio: Walt Disney Animation Studios
type: movie
title: Tangled
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG
summary: 'The magically long-haired Rapunzel has spent her entire life in a tower, but now that a runaway thief has stumbled upon her, she is about to discover the world for the first time, and who she really is.'
rating: 8.9
audienceRating: 8.7
viewCount: 1
lastViewedAt: 1704936047
year: 2010
tagline: They're taking adventure to new lengths.
thumb: /library/metadata/14944/thumb/1705739847
art: /library/metadata/14944/art/1705739847
duration: 6017237
originallyAvailableAt: 2010-11-24T00:00:00.000Z
addedAt: 1589412494
updatedAt: 1705739847
audienceRatingImage: 'rottentomatoes://image.rating.upright'
primaryExtraKey: /library/metadata/14952
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 38247
duration: 6017237
bitrate: 2051
width: 1920
height: 1080
aspectRatio: 1.78
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 1
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 38247
key: /library/parts/38247/1589412494/file.mp4
duration: 6017237
file: /movies/Tangled (2010)/Tangled (2010) Bluray-1080p.mp4
size: 1545647447
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: true
videoProfile: high
Genre:
- tag: Comedy
- tag: Animation
Country:
- tag: United States of America
Director:
- tag: Byron Howard
- tag: Nathan Greno
Writer:
- tag: Jacob Grimm
- tag: Wilhelm Grimm
Role:
- tag: Mandy Moore
- tag: Zachary Levi
- tag: Donna Murphy
promoted: true
random: true
'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
/identity:
get:
tags:
- Server
summary: Get Server Identity
description: Get Server Identity
operationId: getServerIdentity
responses:
'200':
description: The Server Identity information
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 0
claimed:
type: boolean
machineIdentifier:
type: string
example: 96f2fe7a78c9dc1f16a16bedbe90f98149be16b4
version:
type: string
example: 1.31.3.6868-28fc46b27
'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
/library/hashes:
get:
tags:
- Library
summary: Get Hash Value
description: This resource returns hash values for local files
operationId: getFileHash
parameters:
- name: url
description: 'This is the path to the local file, must be prefixed by `file://`'
in: query
schema:
type: string
example: 'file://C:\Image.png&type=13'
required: true
- name: type
description: Item type
in: query
schema:
type: number
required: false
responses:
'200':
description: The hash of the file
'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
/library/recentlyAdded:
get:
tags:
- Library
summary: Get Recently Added
description: |
This endpoint will return the recently added content.
operationId: getRecentlyAdded
responses:
'200':
description: The recently added content
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 50
allowSync:
type: boolean
identifier:
type: string
example: com.plexapp.plugins.library
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: number
example: 1680021154
mixedParents:
type: boolean
Metadata:
type: array
items:
type: object
properties:
allowSync:
type: boolean
librarySectionID:
type: number
example: 1
librarySectionTitle:
type: string
example: Movies
librarySectionUUID:
type: string
example: 322a231a-b7f7-49f5-920f-14c61199cd30
ratingKey:
type: number
example: 59398
key:
type: string
example: /library/metadata/59398
guid:
type: string
example: 'plex://movie/5e161a83bea6ac004126e148'
studio:
type: string
example: Marvel Studios
type:
type: string
example: movie
title:
type: string
example: 'Ant-Man and the Wasp: Quantumania'
contentRating:
type: string
example: PG-13
summary:
type: string
example: Scott Lang and Hope Van Dyne along with Hank Pym and Janet Van Dyne explore the Quantum Realm where they interact with strange creatures and embark on an adventure that goes beyond the limits of what they thought was possible.
rating:
type: number
example: 4.7
audienceRating:
type: number
example: 8.3
year:
type: number
example: 2023
tagline:
type: string
example: Witness the beginning of a new dynasty.
thumb:
type: string
example: /library/metadata/59398/thumb/1681888010
art:
type: string
example: /library/metadata/59398/art/1681888010
duration:
type: number
example: 7474422
originallyAvailableAt:
type: string
format: date-time
example: 2023-02-15T00:00:00.000Z
addedAt:
type: number
example: 1681803215
updatedAt:
type: number
example: 1681888010
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
chapterSource:
type: string
example: media
primaryExtraKey:
type: string
example: /library/metadata/59399
ratingImage:
type: string
example: 'rottentomatoes://image.rating.rotten'
Media:
type: array
items:
type: object
properties:
id:
type: number
example: 120345
duration:
type: number
example: 7474422
bitrate:
type: number
example: 3623
width:
type: number
example: 1920
height:
type: number
example: 804
aspectRatio:
type: number
example: 2.35
audioChannels:
type: number
example: 6
audioCodec:
type: string
example: ac3
videoCodec:
type: string
example: h264
videoResolution:
type: number
example: 1080
container:
type: string
example: mp4
videoFrameRate:
type: string
example: 24p
optimizedForStreaming:
type: number
example: 0
has64bitOffsets:
type: boolean
videoProfile:
type: string
example: high
Part:
type: array
items:
type: object
properties:
id:
type: number
example: 120353
key:
type: string
example: /library/parts/120353/1681803203/file.mp4
duration:
type: number
example: 7474422
file:
type: string
example: /movies/Ant-Man and the Wasp Quantumania (2023)/Ant-Man.and.the.Wasp.Quantumania.2023.1080p.mp4
size:
type: number
example: 3395307162
container:
type: string
example: mp4
has64bitOffsets:
type: boolean
hasThumbnail:
type: number
example: 1
optimizedForStreaming:
type: boolean
videoProfile:
type: string
example: high
Genre:
type: array
items:
type: object
properties:
tag:
type: string
example: Comedy
Director:
type: array
items:
type: object
properties:
tag:
type: string
example: Peyton Reed
Writer:
type: array
items:
type: object
properties:
tag:
type: string
example: Jeff Loveness
Country:
type: array
items:
type: object
properties:
tag:
type: string
example: United States of America
Role:
type: array
items:
type: object
properties:
tag:
type: string
example: Paul Rudd
'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
/library/sections:
get:
tags:
- Library
summary: Get All Libraries
operationId: getLibraries
description: |
A library section (commonly referred to as just a library) is a collection of media.
Libraries are typed, and depending on their type provide either a flat or a hierarchical view of the media.
For example, a music library has an artist > albums > tracks structure, whereas a movie library is flat.
Libraries have features beyond just being a collection of media; for starters, they include information about supported types, filters and sorts.
This allows a client to provide a rich interface around the media (e.g. allow sorting movies by release year).
responses:
'200':
description: The libraries available on the Server
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 5
allowSync:
type: boolean
example: false
title1:
type: string
example: Plex Library
Directory:
type: array
items:
type: object
properties:
allowSync:
type: boolean
example: true
art:
type: string
example: '/:/resources/movie-fanart.jpg'
composite:
type: string
example: /library/sections/1/composite/1705615584
filters:
type: boolean
example: true
refreshing:
type: boolean
example: false
thumb:
type: string
example: '/:/resources/movie.png'
key:
type: string
example: '1'
type:
type: string
example: movie
title:
type: string
example: Movies
agent:
type: string
example: tv.plex.agents.movie
scanner:
type: string
example: Plex Movie
language:
type: string
example: en-US
uuid:
type: string
example: 322a231a-b7f7-49f5-920f-14c61199cd30
updatedAt:
type: integer
format: int32
example: 1705615634
createdAt:
type: integer
format: int32
example: 1654131312
scannedAt:
type: integer
format: int32
example: 1705615584
content:
type: boolean
example: true
directory:
type: boolean
example: true
contentChangedAt:
type: integer
format: int32
example: 3192854
hidden:
type: integer
format: int32
example: 0
Location:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 1
path:
type: string
example: /movies
example:
- id: 1
path: /movies
example:
- allowSync: true
art: '/:/resources/movie-fanart.jpg'
composite: /library/sections/1/composite/1705615584
filters: true
refreshing: false
thumb: '/:/resources/movie.png'
key: '1'
type: movie
title: Movies
agent: tv.plex.agents.movie
scanner: Plex Movie
language: en-US
uuid: 322a231a-b7f7-49f5-920f-14c61199cd30
updatedAt: 1705615634
createdAt: 1654131312
scannedAt: 1705615584
content: true
directory: true
contentChangedAt: 3192854
hidden: 0
Location:
- id: 1
path: /movies
'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
'/library/sections/{sectionId}':
get:
tags:
- Library
summary: Get Library Details
description: |
## Library Details Endpoint
This endpoint provides comprehensive details about the library, focusing on organizational aspects rather than the content itself.
The details include:
### Directories
Organized into three categories:
- **Primary Directories**:
- Used in some clients for quick access to media subsets (e.g., "All", "On Deck").
- Most can be replicated via media queries.
- Customizable by users.
- **Secondary Directories**:
- Marked with `secondary="1"`.
- Used in older clients for structured navigation.
- **Special Directories**:
- Includes a "By Folder" entry for filesystem-based browsing.
- Contains an obsolete `search="1"` entry for on-the-fly search dialog creation.
### Types
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
- **Type Object Attributes**:
- `key`: Endpoint for the media list of this type.
- `type`: Metadata type (if standard Plex type).
- `title`: Title for this content type (e.g., "Movies").
- **Filter Objects**:
- Subset of the media query language.
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
- **Sort Objects**:
- Description of sort fields.
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
operationId: getLibrary
parameters:
- name: sectionId
description: the Id of the library to query
in: path
schema:
type: number
example: 1000
required: true
- name: includeDetails
description: |
Whether or not to include details for a section (types, filters, and sorts).
Only exists for backwards compatibility, media providers other than the server libraries have it on always.
in: query
schema:
type: integer
enum:
- 0
- 1
default: 0
required: false
responses:
'200':
description: The details of the library
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 29
allowSync:
type: boolean
example: false
art:
type: string
example: '/:/resources/movie-fanart.jpg'
content:
type: string
example: secondary
identifier:
type: string
example: com.plexapp.plugins.library
librarySectionID:
type: integer
format: int32
example: 1
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: integer
format: int32
example: 1701731894
thumb:
type: string
example: '/:/resources/movie.png'
title1:
type: string
example: Movies
viewGroup:
type: string
example: secondary
viewMode:
type: integer
format: int32
example: 65592
Directory:
type: array
items:
type: object
properties:
key:
type: string
example: search?type=1
title:
type: string
example: Search...
secondary:
type: boolean
example: true
prompt:
type: string
example: Search Movies
search:
type: boolean
example: true
example:
- key: search?type=1
title: Search...
secondary: true
prompt: Search Movies
search: true
Type:
type: array
items:
type: object
properties:
key:
type: string
example: /library/sections/1/all?type=1
type:
type: string
example: movie
title:
type: string
example: Movies
active:
type: boolean
example: false
Filter:
type: array
items:
type: object
properties:
filter:
type: string
example: label
filterType:
type: string
example: string
key:
type: string
example: /library/sections/1/label
title:
type: string
example: Labels
type:
type: string
example: filter
example:
- filter: label
filterType: string
key: /library/sections/1/label
title: Labels
type: filter
Sort:
type: array
items:
type: object
properties:
default:
type: string
example: asc
defaultDirection:
type: string
example: desc
descKey:
type: string
example: 'random:desc'
firstCharacterKey:
type: string
example: /library/sections/1/firstCharacter
key:
type: string
example: random
title:
type: string
example: Randomly
example:
- default: asc
defaultDirection: desc
descKey: 'random:desc'
firstCharacterKey: /library/sections/1/firstCharacter
key: random
title: Randomly
Field:
type: array
items:
type: object
properties:
key:
type: string
example: label
title:
type: string
example: Label
type:
type: string
example: tag
subType:
type: string
example: bitrate
example:
- key: label
title: Label
type: tag
subType: bitrate
example:
- key: /library/sections/1/all?type=1
type: movie
title: Movies
active: false
Filter:
- filter: genre
filterType: string
key: /library/sections/1/genre
title: Genre
type: filter
- filter: year
filterType: integer
key: /library/sections/1/year
title: Year
type: filter
- filter: decade
filterType: integer
key: /library/sections/1/decade
title: Decade
type: filter
- filter: contentRating
filterType: string
key: /library/sections/1/contentRating
title: Content Rating
type: filter
- filter: collection
filterType: string
key: /library/sections/1/collection
title: Collection
type: filter
- filter: director
filterType: string
key: /library/sections/1/director
title: Director
type: filter
- filter: actor
filterType: string
key: /library/sections/1/actor
title: Actor
type: filter
- filter: writer
filterType: string
key: /library/sections/1/writer
title: Writer
type: filter
- filter: producer
filterType: string
key: /library/sections/1/producer
title: Producer
type: filter
- filter: country
filterType: string
key: /library/sections/1/country
title: Country
type: filter
- filter: studio
filterType: string
key: /library/sections/1/studio
title: Studio
type: filter
- filter: resolution
filterType: string
key: /library/sections/1/resolution
title: Resolution
type: filter
- filter: hdr
filterType: boolean
key: /library/sections/1/hdr
title: HDR
type: filter
- filter: unwatched
filterType: boolean
key: /library/sections/1/unwatched
title: Unplayed
type: filter
- filter: inProgress
filterType: boolean
key: /library/sections/1/inProgress
title: In Progress
type: filter
- filter: unmatched
filterType: boolean
key: /library/sections/1/unmatched
title: Unmatched
type: filter
- filter: audioLanguage
filterType: string
key: /library/sections/1/audioLanguage
title: Audio Language
type: filter
- filter: subtitleLanguage
filterType: string
key: /library/sections/1/subtitleLanguage
title: Subtitle Language
type: filter
- filter: editionTitle
filterType: string
key: /library/sections/1/editionTitle
title: Edition
type: filter
- filter: label
filterType: string
key: /library/sections/1/label
title: Labels
type: filter
Sort:
- default: asc
defaultDirection: asc
descKey: 'titleSort:desc'
firstCharacterKey: /library/sections/1/firstCharacter
key: titleSort
title: Title
- defaultDirection: desc
descKey: 'originallyAvailableAt:desc'
key: originallyAvailableAt
title: Release Date
- defaultDirection: desc
descKey: 'rating:desc'
key: rating
title: Critic Rating
- defaultDirection: desc
descKey: 'audienceRating:desc'
key: audienceRating
title: Audience Rating
- defaultDirection: desc
descKey: 'duration:desc'
key: duration
title: Duration
- defaultDirection: desc
descKey: 'addedAt:desc'
key: addedAt
title: Date Added
- defaultDirection: desc
descKey: 'lastViewedAt:desc'
key: lastViewedAt
title: Date Viewed
- defaultDirection: asc
descKey: 'mediaHeight:desc'
key: mediaHeight
title: Resolution
- defaultDirection: desc
descKey: 'random:desc'
key: random
title: Randomly
Field:
- key: title
title: Title
type: string
- key: studio
title: Studio
type: string
- key: userRating
subType: rating
title: Rating
type: integer
- key: contentRating
title: Content Rating
type: tag
- key: year
subType: year
title: Year
type: integer
- key: decade
subType: decade
title: Decade
type: integer
- key: originallyAvailableAt
title: Release Date
type: date
- key: duration
subType: duration
title: Duration
type: integer
- key: unmatched
title: Unmatched
type: boolean
- key: duplicate
title: Duplicate
type: boolean
- key: genre
title: Genre
type: tag
- key: collection
title: Collection
type: tag
- key: director
title: Director
type: tag
- key: writer
title: Writer
type: tag
- key: producer
title: Producer
type: tag
- key: actor
title: Actor
type: tag
- key: country
title: Country
type: tag
- key: addedAt
title: Date Added
type: date
- key: viewCount
title: Plays
type: integer
- key: lastViewedAt
title: Last Played
type: date
- key: unwatched
title: Unplayed
type: boolean
- key: resolution
title: Resolution
type: resolution
- key: hdr
subType: hdr
title: HDR
type: boolean
- key: mediaSize
subType: fileSize
title: File Size
type: integer
- key: mediaBitrate
subType: bitrate
title: Bitrate
type: integer
- key: subtitleLanguage
title: Subtitle Language
type: subtitleLanguage
- key: audioLanguage
title: Audio Language
type: audioLanguage
- key: inProgress
title: In Progress
type: boolean
- key: trash
title: Trash
type: boolean
- key: editionTitle
title: Edition
type: string
- key: label
title: Label
type: tag
FieldType:
type: array
items:
type: object
properties:
type:
type: string
example: resolution
Operator:
type: array
items:
type: object
properties:
key:
type: string
example: '='
title:
type: string
example: is
example:
- key: '='
title: is
example:
- type: resolution
Operator:
- key: '='
title: is
'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
delete:
tags:
- Library
summary: Delete Library Section
description: Delate a library using a specific section
operationId: deleteLibrary
parameters:
- name: sectionId
description: the Id of the library to query
in: path
schema:
type: number
example: 1000
required: true
responses:
'200':
description: The library is deleted
'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
'/library/sections/{sectionId}/{tag}':
get:
tags:
- Library
summary: Get Library Items
operationId: getLibraryItems
description: |
Fetches details from a specific section of the library identified by a section key and a tag. The tag parameter accepts the following values:
- `all`: All items in the section.
- `unwatched`: Items that have not been played.
- `newest`: Items that are recently released.
- `recentlyAdded`: Items that are recently added to the library.
- `recentlyViewed`: Items that were recently viewed.
- `onDeck`: Items to continue watching.
- `collection`: Items categorized by collection.
- `edition`: Items categorized by edition.
- `genre`: Items categorized by genre.
- `year`: Items categorized by year of release.
- `decade`: Items categorized by decade.
- `director`: Items categorized by director.
- `actor`: Items categorized by starring actor.
- `country`: Items categorized by country of origin.
- `contentRating`: Items categorized by content rating.
- `rating`: Items categorized by rating.
- `resolution`: Items categorized by resolution.
- `firstCharacter`: Items categorized by the first letter.
- `folder`: Items categorized by folder.
parameters:
- name: sectionId
in: path
required: true
description: the Id of the library to query
schema:
type: integer
- name: tag
in: path
required: true
description: A key representing a specific tag within the section.
schema:
type: string
enum:
- all
- unwatched
- newest
- recentlyAdded
- recentlyViewed
- onDeck
- collection
- edition
- genre
- year
- decade
- director
- actor
- country
- contentRating
- rating
- resolution
- firstCharacter
- folder
responses:
'200':
description: The contents of the library by section and tag
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 70
allowSync:
type: boolean
example: true
art:
type: string
example: '/:/resources/movie-fanart.jpg'
identifier:
type: string
example: com.plexapp.plugins.library
librarySectionID:
type: integer
format: int32
example: 1
librarySectionTitle:
type: string
example: Movies
librarySectionUUID:
type: string
example: 322a231a-b7f7-49f5-920f-14c61199cd30
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: integer
format: int32
example: 1701731894
thumb:
type: string
example: '/:/resources/movie.png'
title1:
type: string
example: Movies
title2:
type: string
example: Recently Released
viewGroup:
type: string
example: movie
viewMode:
type: integer
format: int32
example: 65592
mixedParents:
type: boolean
example: true
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '58683'
key:
type: string
example: /library/metadata/58683
guid:
type: string
example: 'plex://movie/5d7768ba96b655001fdc0408'
studio:
type: string
example: 20th Century Studios
type:
type: string
example: movie
title:
type: string
example: 'Avatar: The Way of Water'
contentRating:
type: string
example: PG-13
summary:
type: string
example: 'Jake Sully lives with his newfound family formed on the extrasolar moon Pandora. Once a familiar threat returns to finish what was previously started, Jake must work with Neytiri and the army of the Na''vi race to protect their home.'
rating:
type: number
example: 7.6
audienceRating:
type: number
example: 9.2
year:
type: integer
format: int32
example: 2022
tagline:
type: string
example: Return to Pandora.
thumb:
type: string
example: /library/metadata/58683/thumb/1703239236
art:
type: string
example: /library/metadata/58683/art/1703239236
duration:
type: integer
format: int32
example: 11558112
originallyAvailableAt:
type: string
format: date
example: 2022-12-14T00:00:00.000Z
addedAt:
type: integer
format: int32
example: 1680457607
updatedAt:
type: integer
format: int32
example: 1703239236
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
chapterSource:
type: string
example: media
primaryExtraKey:
type: string
example: /library/metadata/58684
ratingImage:
type: string
example: 'rottentomatoes://image.rating.ripe'
grandparentRatingKey:
type: string
example: '66'
grandparentGuid:
type: string
example: 'plex://show/5d9c081b170e24001f2a7be4'
grandparentKey:
type: string
example: /library/metadata/66
grandparentTitle:
type: string
example: Caprica
grandparentThumb:
type: string
example: /library/metadata/66/thumb/1705716261
grandparentArt:
type: string
example: /library/metadata/66/art/1705716261
grandparentTheme:
type: string
example: /library/metadata/66/theme/1705716261
Media:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 119534
duration:
type: integer
format: int32
example: 11558112
bitrate:
type: integer
format: int32
example: 25025
width:
type: integer
format: int32
example: 3840
height:
type: integer
format: int32
example: 2072
aspectRatio:
type: number
example: 1.85
audioChannels:
type: integer
format: int32
example: 6
audioCodec:
type: string
example: eac3
videoCodec:
type: string
example: hevc
videoResolution:
type: string
example: 4k
container:
type: string
example: mkv
videoFrameRate:
type: string
example: 24p
videoProfile:
type: string
example: main 10
Part:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 119542
key:
type: string
example: /library/parts/119542/1680457526/file.mkv
duration:
type: integer
format: int32
example: 11558112
file:
type: string
example: /movies/Avatar The Way of Water (2022)/Avatar.The.Way.of.Water.2022.2160p.WEB-DL.DDP5.1.Atmos.DV.HDR10.HEVC-CMRG.mkv
size:
type: integer
format: int64
example: 36158371307
container:
type: string
example: mkv
videoProfile:
type: string
example: main 10
example:
- id: 119542
key: /library/parts/119542/1680457526/file.mkv
duration: 11558112
file: /movies/Avatar The Way of Water (2022)/Avatar.The.Way.of.Water.2022.2160p.WEB-DL.DDP5.1.Atmos.DV.HDR10.HEVC-CMRG.mkv
size: 36158371307
container: mkv
videoProfile: main 10
example:
- id: 119534
duration: 11558112
bitrate: 25025
width: 3840
height: 2072
aspectRatio: 1.85
audioChannels: 6
audioCodec: eac3
videoCodec: hevc
videoResolution: 4k
container: mkv
videoFrameRate: 24p
videoProfile: main 10
Part:
- id: 119542
key: /library/parts/119542/1680457526/file.mkv
duration: 11558112
file: /movies/Avatar The Way of Water (2022)/Avatar.The.Way.of.Water.2022.2160p.WEB-DL.DDP5.1.Atmos.DV.HDR10.HEVC-CMRG.mkv
size: 36158371307
container: mkv
videoProfile: main 10
Genre:
type: array
items:
type: object
properties:
tag:
type: string
example: Adventure
example:
- tag: Adventure
Country:
type: array
items:
type: object
properties:
tag:
type: string
example: United States of America
example:
- tag: United States of America
Director:
type: array
items:
type: object
properties:
tag:
type: string
example: James Cameron
example:
- tag: James Cameron
Writer:
type: array
items:
type: object
properties:
tag:
type: string
example: James Cameron
example:
- tag: James Cameron
Role:
type: array
items:
type: object
properties:
tag:
type: string
example: Sigourney Weaver
example:
- tag: Sigourney Weaver
titleSort:
type: string
example: Whale
viewCount:
type: integer
format: int32
example: 1
lastViewedAt:
type: integer
format: int32
example: 1682752242
originalTitle:
type: string
example: 映画 ブラッククローバー 魔法帝の剣
viewOffset:
type: integer
format: int32
example: 5222500
skipCount:
type: integer
format: int32
example: 1
index:
type: integer
format: int32
example: 1
theme:
type: string
example: /library/metadata/1/theme/1705636920
leafCount:
type: integer
format: int32
example: 14
viewedLeafCount:
type: integer
format: int32
example: 0
childCount:
type: integer
format: int32
example: 1
hasPremiumExtras:
type: string
example: '1'
hasPremiumPrimaryExtra:
type: string
example: '1'
parentRatingKey:
type: string
example: '66'
parentGuid:
type: string
example: 'plex://show/5d9c081b170e24001f2a7be4'
parentStudio:
type: string
example: UCP
parentKey:
type: string
example: /library/metadata/66
parentTitle:
type: string
example: Caprica
parentIndex:
type: integer
format: int32
example: 1
parentYear:
type: integer
format: int32
example: 2010
parentThumb:
type: string
example: /library/metadata/66/thumb/1705716261
parentTheme:
type: string
example: /library/metadata/66/theme/1705716261
example:
- ratingKey: '58683'
key: /library/metadata/58683
guid: 'plex://movie/5d7768ba96b655001fdc0408'
studio: 20th Century Studios
type: movie
title: 'Avatar: The Way of Water'
contentRating: PG-13
summary: 'Jake Sully lives with his newfound family formed on the extrasolar moon Pandora. Once a familiar threat returns to finish what was previously started, Jake must work with Neytiri and the army of the Na''vi race to protect their home.'
rating: 7.6
audienceRating: 9.2
year: 2022
tagline: Return to Pandora.
thumb: /library/metadata/58683/thumb/1703239236
art: /library/metadata/58683/art/1703239236
duration: 11558112
originallyAvailableAt: 2022-12-14T00:00:00.000Z
addedAt: 1680457607
updatedAt: 1703239236
audienceRatingImage: 'rottentomatoes://image.rating.upright'
chapterSource: media
primaryExtraKey: /library/metadata/58684
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 119534
duration: 11558112
bitrate: 25025
width: 3840
height: 2072
aspectRatio: 1.85
audioChannels: 6
audioCodec: eac3
videoCodec: hevc
videoResolution: 4k
container: mkv
videoFrameRate: 24p
videoProfile: main 10
Part:
- id: 119542
key: /library/parts/119542/1680457526/file.mkv
duration: 11558112
file: /movies/Avatar The Way of Water (2022)/Avatar.The.Way.of.Water.2022.2160p.WEB-DL.DDP5.1.Atmos.DV.HDR10.HEVC-CMRG.mkv
size: 36158371307
container: mkv
videoProfile: main 10
Genre:
- tag: Action
- tag: Adventure
Country:
- tag: United States of America
Director:
- tag: James Cameron
Writer:
- tag: Josh Friedman
- tag: James Cameron
Role:
- tag: Sam Worthington
- tag: Zoe Saldaña
- tag: Sigourney Weaver
titleSort: Whale
viewCount: 1
lastViewedAt: 1682752242
originalTitle: 映画 ブラッククローバー 魔法帝の剣
viewOffset: 5222500
skipCount: 1
index: 1
theme: /library/metadata/1/theme/1705636920
leafCount: 14
viewedLeafCount: 0
childCount: 1
hasPremiumExtras: '1'
hasPremiumPrimaryExtra: '1'
parentRatingKey: '66'
parentGuid: 'plex://show/5d9c081b170e24001f2a7be4'
parentStudio: UCP
parentKey: /library/metadata/66
parentTitle: Caprica
parentIndex: 1
parentYear: 2010
parentThumb: /library/metadata/66/thumb/1705716261
parentTheme: /library/metadata/66/theme/1705716261
grandparentRatingKey: '66'
grandparentGuid: 'plex://show/5d9c081b170e24001f2a7be4'
grandparentKey: /library/metadata/66
grandparentTitle: Caprica
grandparentThumb: /library/metadata/66/thumb/1705716261
grandparentArt: /library/metadata/66/art/1705716261
grandparentTheme: /library/metadata/66/theme/1705716261
'/library/sections/{sectionId}/refresh':
get:
tags:
- Library
summary: Refresh Library
description: |
This endpoint Refreshes the library.
operationId: refreshLibrary
parameters:
- name: sectionId
description: the Id of the library to refresh
in: path
schema:
type: number
required: true
responses:
'200':
description: The library is refreshing
'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
'/library/sections/{sectionId}/search':
get:
tags:
- Library
summary: Search Library
operationId: searchLibrary
description: |
Search for content within a specific section of the library.
### Types
Each type in the library comes with a set of filters and sorts, aiding in building dynamic media controls:
- **Type Object Attributes**:
- `type`: Metadata type (if standard Plex type).
- `title`: Title for this content type (e.g., "Movies").
- **Filter Objects**:
- Subset of the media query language.
- Attributes include `filter` (name), `filterType` (data type), `key` (endpoint for value range), and `title`.
- **Sort Objects**:
- Description of sort fields.
- Attributes include `defaultDirection` (asc/desc), `descKey` and `key` (sort parameters), and `title`.
> **Note**: Filters and sorts are optional; without them, no filtering controls are rendered.
parameters:
- name: sectionId
in: path
required: true
description: the Id of the library to query
schema:
type: integer
- name: type
description: Plex content type to search for
in: query
schema:
type: integer
enum:
- 1
- 2
- 3
- 4
required: true
responses:
'200':
description: The contents of the library by section and type
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 2
allowSync:
type: boolean
example: false
art:
type: string
example: '/:/resources/show-fanart.jpg'
identifier:
type: string
example: com.plexapp.plugins.library
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: integer
format: int32
example: 1698860922
nocache:
type: boolean
example: true
thumb:
type: string
example: '/:/resources/show.png'
title1:
type: string
example: TV Shows
title2:
type: string
example: Search for ''
viewGroup:
type: string
example: season
viewMode:
type: integer
format: int32
example: 65593
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '2'
key:
type: string
example: /library/metadata/2/children
parentRatingKey:
type: string
example: '1'
guid:
type: string
example: 'plex://season/602e67e766dfdb002c0a1b5b'
parentGuid:
type: string
example: 'plex://show/5d9c086c7d06d9001ffd27aa'
parentStudio:
type: string
example: Mutant Enemy Productions
type:
type: string
example: season
title:
type: string
example: Season 1
parentKey:
type: string
example: /library/metadata/1
parentTitle:
type: string
example: Firefly
summary:
type: string
example: 'Captain Malcolm ''Mal'' Reynolds is a former galactic war veteran who is the captain of the transport ship "Serenity". Mal and his crew, ensign Zoe Alleyne Washburne; Zoe''s husband, pilot Hoban ''Wash'' Washburne; muscular mercenary Jayne Cobb; young mechanic Kaylee Frye; former Alliance medical officer Simon Tam; his disturbed teenage sister River (both on the run from the interplanetary government "The Alliance"); the beautiful courtesan Inara Serra; and preacher Shepherd Book do any jobs, legal or illegal, they can find as the Serenity crew travels across the outskirts of outer space.'
index:
type: integer
format: int32
example: 1
parentIndex:
type: integer
format: int32
example: 1
parentYear:
type: integer
format: int32
example: 2002
thumb:
type: string
example: /library/metadata/2/thumb/1705636920
art:
type: string
example: /library/metadata/1/art/1705636920
parentThumb:
type: string
example: /library/metadata/1/thumb/1705636920
parentTheme:
type: string
example: /library/metadata/1/theme/1705636920
addedAt:
type: integer
format: int32
example: 1705636916
updatedAt:
type: integer
format: int32
example: 1705636920
example:
- ratingKey: '2'
key: /library/metadata/2/children
parentRatingKey: '1'
guid: 'plex://season/602e67e766dfdb002c0a1b5b'
parentGuid: 'plex://show/5d9c086c7d06d9001ffd27aa'
parentStudio: Mutant Enemy Productions
type: season
title: Season 1
parentKey: /library/metadata/1
parentTitle: Firefly
summary: 'Captain Malcolm ''Mal'' Reynolds is a former galactic war veteran who is the captain of the transport ship "Serenity". Mal and his crew, ensign Zoe Alleyne Washburne; Zoe''s husband, pilot Hoban ''Wash'' Washburne; muscular mercenary Jayne Cobb; young mechanic Kaylee Frye; former Alliance medical officer Simon Tam; his disturbed teenage sister River (both on the run from the interplanetary government "The Alliance"); the beautiful courtesan Inara Serra; and preacher Shepherd Book do any jobs, legal or illegal, they can find as the Serenity crew travels across the outskirts of outer space.'
index: 1
parentIndex: 1
parentYear: 2002
thumb: /library/metadata/2/thumb/1705636920
art: /library/metadata/1/art/1705636920
parentThumb: /library/metadata/1/thumb/1705636920
parentTheme: /library/metadata/1/theme/1705636920
addedAt: 1705636916
updatedAt: 1705636920
'/library/metadata/{ratingKey}':
get:
tags:
- Library
summary: Get Items Metadata
description: |
This endpoint will return the metadata of a library item specified with the ratingKey.
operationId: getMetadata
parameters:
- name: ratingKey
description: the id of the library item to return the children of.
in: path
schema:
type: number
required: true
responses:
'200':
description: The metadata of the library item.
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
allowSync:
type: boolean
example: true
identifier:
type: string
example: com.plexapp.plugins.library
librarySectionID:
type: integer
format: int32
example: 1
librarySectionTitle:
type: string
example: Movies
librarySectionUUID:
type: string
example: cfc899d7-3000-46f6-8489-b9592714ada5
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: integer
format: int32
example: 1698860922
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '17'
key:
type: string
example: /library/metadata/17
guid:
type: string
example: 'plex://movie/5d77683f6f4521001ea9dc53'
studio:
type: string
example: Universal Pictures
type:
type: string
example: movie
title:
type: string
example: Serenity
librarySectionTitle:
type: string
example: Movies
librarySectionID:
type: integer
format: int32
example: 1
librarySectionKey:
type: string
example: /library/sections/1
contentRating:
type: string
example: PG-13
summary:
type: string
example: 'Serenity continues the story of the TV series it was based upon ("Firefly"). River Tam had a secret - one in which she''s not even aware - so dangerous, no one''s safe, as an Alliance operative''s sent to capture her, and all others are considered irrelevant to his job.'
rating:
type: number
example: 8.2
audienceRating:
type: number
example: 9.1
year:
type: integer
format: int32
example: 2005
tagline:
type: string
example: They aim to misbehave.
thumb:
type: string
example: /library/metadata/17/thumb/1705637165
art:
type: string
example: /library/metadata/17/art/1705637165
duration:
type: integer
format: int32
example: 141417
originallyAvailableAt:
type: string
format: date
example: 2005-09-29T00:00:00.000Z
addedAt:
type: integer
format: int32
example: 1705637164
updatedAt:
type: integer
format: int32
example: 1705637165
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
hasPremiumPrimaryExtra:
type: string
example: '1'
ratingImage:
type: string
example: 'rottentomatoes://image.rating.ripe'
Media:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 15
duration:
type: integer
format: int32
example: 141417
bitrate:
type: integer
format: int32
example: 2278
width:
type: integer
format: int32
example: 1920
height:
type: integer
format: int32
example: 814
aspectRatio:
type: number
example: 2.35
audioChannels:
type: integer
format: int32
example: 2
audioCodec:
type: string
example: aac
videoCodec:
type: string
example: h264
videoResolution:
type: string
example: '1080'
container:
type: string
example: mp4
videoFrameRate:
type: string
example: 24p
optimizedForStreaming:
type: integer
format: int32
example: 0
audioProfile:
type: string
example: lc
has64bitOffsets:
type: boolean
example: false
videoProfile:
type: string
example: high
Part:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 15
key:
type: string
example: /library/parts/15/1705637151/file.mp4
duration:
type: integer
format: int32
example: 141417
file:
type: string
example: /movies/Serenity (2005)/Serenity (2005).mp4
size:
type: integer
format: int32
example: 40271948
audioProfile:
type: string
example: lc
container:
type: string
example: mp4
has64bitOffsets:
type: boolean
example: false
optimizedForStreaming:
type: boolean
example: false
videoProfile:
type: string
example: high
Stream:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 29
streamType:
type: integer
format: int32
example: 2
default:
type: boolean
example: true
codec:
type: string
example: aac
index:
type: integer
format: int32
example: 0
bitrate:
type: integer
format: int32
example: 128
bitDepth:
type: integer
format: int32
example: 8
chromaLocation:
type: string
example: left
chromaSubsampling:
type: string
example: 14520
codedHeight:
type: integer
format: int32
example: 816
codedWidth:
type: integer
format: int32
example: 1920
colorPrimaries:
type: string
example: bt709
colorRange:
type: string
example: tv
colorSpace:
type: string
example: bt709
colorTrc:
type: string
example: bt709
frameRate:
type: integer
format: int32
example: 24
hasScalingMatrix:
type: boolean
example: false
height:
type: integer
format: int32
example: 814
level:
type: integer
format: int32
example: 40
profile:
type: string
example: lc
refFrames:
type: integer
format: int32
example: 4
scanType:
type: string
example: progressive
streamIdentifier:
type: string
example: '1'
width:
type: integer
format: int32
example: 1920
displayTitle:
type: string
example: English (AAC Stereo)
extendedDisplayTitle:
type: string
example: English (AAC Stereo)
selected:
type: boolean
example: true
channels:
type: integer
format: int32
example: 2
language:
type: string
example: English
languageTag:
type: string
example: en
languageCode:
type: string
example: eng
samplingRate:
type: integer
format: int32
example: 44100
example:
- id: 29
streamType: 2
default: true
codec: aac
index: 0
bitrate: 128
bitDepth: 8
chromaLocation: left
chromaSubsampling: 14520
codedHeight: 816
codedWidth: 1920
colorPrimaries: bt709
colorRange: tv
colorSpace: bt709
colorTrc: bt709
frameRate: 24
hasScalingMatrix: false
height: 814
level: 40
profile: lc
refFrames: 4
scanType: progressive
streamIdentifier: '1'
width: 1920
displayTitle: English (AAC Stereo)
extendedDisplayTitle: English (AAC Stereo)
selected: true
channels: 2
language: English
languageTag: en
languageCode: eng
samplingRate: 44100
example:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141417
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Stream:
- id: 30
streamType: 1
default: true
codec: h264
index: 1
bitrate: 2160
bitDepth: 8
chromaLocation: left
chromaSubsampling: 14520
codedHeight: 816
codedWidth: 1920
colorPrimaries: bt709
colorRange: tv
colorSpace: bt709
colorTrc: bt709
frameRate: 24
hasScalingMatrix: false
height: 814
level: 40
profile: high
refFrames: 4
scanType: progressive
streamIdentifier: '2'
width: 1920
displayTitle: 1080p (H.264)
extendedDisplayTitle: 1080p (H.264)
- id: 29
streamType: 2
selected: true
default: true
codec: aac
index: 0
channels: 2
bitrate: 128
language: English
languageTag: en
languageCode: eng
profile: lc
samplingRate: 44100
streamIdentifier: '1'
displayTitle: English (AAC Stereo)
extendedDisplayTitle: English (AAC Stereo)
example:
- id: 15
duration: 141417
bitrate: 2278
width: 1920
height: 814
aspectRatio: 2.35
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 0
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141417
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Stream:
- id: 30
streamType: 1
default: true
codec: h264
index: 1
bitrate: 2160
bitDepth: 8
chromaLocation: left
chromaSubsampling: 14520
codedHeight: 816
codedWidth: 1920
colorPrimaries: bt709
colorRange: tv
colorSpace: bt709
colorTrc: bt709
frameRate: 24
hasScalingMatrix: false
height: 814
level: 40
profile: high
refFrames: 4
scanType: progressive
streamIdentifier: '2'
width: 1920
displayTitle: 1080p (H.264)
extendedDisplayTitle: 1080p (H.264)
- id: 29
streamType: 2
selected: true
default: true
codec: aac
index: 0
channels: 2
bitrate: 128
language: English
languageTag: en
languageCode: eng
profile: lc
samplingRate: 44100
streamIdentifier: '1'
displayTitle: English (AAC Stereo)
extendedDisplayTitle: English (AAC Stereo)
Genre:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 184
filter:
type: string
example: genre=184
tag:
type: string
example: Thriller
example:
- id: 184
filter: genre=184
tag: Thriller
Country:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 116
filter:
type: string
example: country=116
tag:
type: string
example: United States of America
example:
- id: 116
filter: country=116
tag: United States of America
Guid:
x-speakeasy-name-override: guids
type: array
items:
type: object
properties:
id:
type: string
example: 'tvdb://2337'
example:
- id: 'tvdb://2337'
Rating:
x-speakeasy-name-override: ratings
type: array
items:
type: object
properties:
image:
type: string
example: 'themoviedb://image.rating'
value:
type: number
example: 7.4
type:
type: string
example: audience
example:
- image: 'themoviedb://image.rating'
value: 7.4
type: audience
Director:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 130
filter:
type: string
example: director=130
tag:
type: string
example: Joss Whedon
tagKey:
type: string
example: 5d776828880197001ec90e8f
thumb:
type: string
example: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
example:
- id: 130
filter: director=130
tag: Joss Whedon
tagKey: 5d776828880197001ec90e8f
thumb: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
Writer:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 132
filter:
type: string
example: writer=132
tag:
type: string
example: Joss Whedon
tagKey:
type: string
example: 5d776828880197001ec90e8f
thumb:
type: string
example: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
example:
- id: 132
filter: writer=132
tag: Joss Whedon
tagKey: 5d776828880197001ec90e8f
thumb: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
Role:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 220
filter:
type: string
example: actor=220
tag:
type: string
example: Dennis Keiffer
tagKey:
type: string
example: 5d77683554f42c001f8c4708
role:
type: string
example: Bar Guy (uncredited)
thumb:
type: string
example: 'https://metadata-static.plex.tv/6/people/648e9a7ea1d537bccfcd7615134b78ce.jpg'
example:
- id: 220
filter: actor=220
tag: Dennis Keiffer
tagKey: 5d77683554f42c001f8c4708
role: Bar Guy (uncredited)
thumb: 'https://metadata-static.plex.tv/6/people/648e9a7ea1d537bccfcd7615134b78ce.jpg'
Producer:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 221
filter:
type: string
example: producer=221
tag:
type: string
example: Barry Mendel
tagKey:
type: string
example: 5d776826961905001eb90e2b
thumb:
type: string
example: 'https://metadata-static.plex.tv/8/people/87877371326a964634d18556d94547e1.jpg'
example:
- id: 221
filter: producer=221
tag: Barry Mendel
tagKey: 5d776826961905001eb90e2b
thumb: 'https://metadata-static.plex.tv/8/people/87877371326a964634d18556d94547e1.jpg'
example:
- ratingKey: '17'
key: /library/metadata/17
guid: 'plex://movie/5d77683f6f4521001ea9dc53'
studio: Universal Pictures
type: movie
title: Serenity
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG-13
summary: 'Serenity continues the story of the TV series it was based upon ("Firefly"). River Tam had a secret - one in which she''s not even aware - so dangerous, no one''s safe, as an Alliance operative''s sent to capture her, and all others are considered irrelevant to his job.'
rating: 8.2
audienceRating: 9.1
year: 2005
tagline: They aim to misbehave.
thumb: /library/metadata/17/thumb/1705637165
art: /library/metadata/17/art/1705637165
duration: 141417
originallyAvailableAt: 2005-09-29T00:00:00.000Z
addedAt: 1705637164
updatedAt: 1705637165
audienceRatingImage: 'rottentomatoes://image.rating.upright'
hasPremiumPrimaryExtra: '1'
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 15
duration: 141417
bitrate: 2278
width: 1920
height: 814
aspectRatio: 2.35
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 0
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141417
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Stream:
- id: 30
streamType: 1
default: true
codec: h264
index: 1
bitrate: 2160
bitDepth: 8
chromaLocation: left
chromaSubsampling: 14520
codedHeight: 816
codedWidth: 1920
colorPrimaries: bt709
colorRange: tv
colorSpace: bt709
colorTrc: bt709
frameRate: 24
hasScalingMatrix: false
height: 814
level: 40
profile: high
refFrames: 4
scanType: progressive
streamIdentifier: '2'
width: 1920
displayTitle: 1080p (H.264)
extendedDisplayTitle: 1080p (H.264)
- id: 29
streamType: 2
selected: true
default: true
codec: aac
index: 0
channels: 2
bitrate: 128
language: English
languageTag: en
languageCode: eng
profile: lc
samplingRate: 44100
streamIdentifier: '1'
displayTitle: English (AAC Stereo)
extendedDisplayTitle: English (AAC Stereo)
Genre:
- id: 5
filter: genre=5
tag: Science Fiction
Country:
- id: 116
filter: country=116
tag: United States of America
Guid:
- id: 'imdb://tt0379786'
Rating:
- image: 'imdb://image.rating'
value: 7.8
type: audience
Director:
- id: 130
filter: director=130
tag: Joss Whedon
tagKey: 5d776828880197001ec90e8f
thumb: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
Writer:
- id: 132
filter: writer=132
tag: Joss Whedon
tagKey: 5d776828880197001ec90e8f
thumb: 'https://metadata-static.plex.tv/people/5d776828880197001ec90e8f.jpg'
Role:
- id: 8
filter: actor=8
tag: Nathan Fillion
tagKey: 5d7768286f4521001ea9945c
role: Malcolm "Mal" Reynolds
thumb: 'https://metadata-static.plex.tv/4/people/4a2890ca346eb832500b1ed0add89d5e.jpg'
Producer:
- id: 221
filter: producer=221
tag: Barry Mendel
tagKey: 5d776826961905001eb90e2b
thumb: 'https://metadata-static.plex.tv/8/people/87877371326a964634d18556d94547e1.jpg'
'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
'/library/metadata/{ratingKey}/children':
get:
tags:
- Library
summary: Get Items Children
description: |
This endpoint will return the children of of a library item specified with the ratingKey.
operationId: getMetadataChildren
parameters:
- name: ratingKey
description: the id of the library item to return the children of.
in: path
schema:
type: number
required: true
responses:
'200':
description: The children of the library item.
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 3
allowSync:
type: boolean
example: true
art:
type: string
example: /library/metadata/30072/art/1705739923
identifier:
type: string
example: com.plexapp.plugins.library
key:
type: string
example: '30072'
librarySectionID:
type: integer
format: int32
example: 2
librarySectionTitle:
type: string
example: TV Shows
librarySectionUUID:
type: string
example: 4bb2521c-8ba9-459b-aaee-8ab8bc35eabd
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: integer
format: int32
example: 1701731894
nocache:
type: boolean
example: true
parentIndex:
type: integer
format: int32
example: 1
parentTitle:
type: string
example: Reacher
parentYear:
type: integer
format: int32
example: 2022
summary:
type: string
example: 'When retired Military Police Officer Jack Reacher is arrested for a murder he did not commit, he finds himself in the middle of a deadly conspiracy full of dirty cops, shady businessmen, and scheming politicians. With nothing but his wits, he must figure out what is happening in Margrave, Georgia.'
theme:
type: string
example: /library/metadata/30072/theme/1705739923
thumb:
type: string
example: /library/metadata/30072/thumb/1705739923
title1:
type: string
example: TV Shows
title2:
type: string
example: Reacher
viewGroup:
type: string
example: season
viewMode:
type: integer
format: int32
example: 65593
Directory:
type: array
items:
type: object
properties:
leafCount:
type: integer
format: int32
example: 16
thumb:
type: string
example: /library/metadata/30072/thumb/1705739923
viewedLeafCount:
type: integer
format: int32
example: 16
key:
type: string
example: /library/metadata/30072/allLeaves
title:
type: string
example: All episodes
example:
- leafCount: 16
thumb: /library/metadata/30072/thumb/1705739923
viewedLeafCount: 16
key: /library/metadata/30072/allLeaves
title: All episodes
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '66488'
key:
type: string
example: /library/metadata/66488/children
parentRatingKey:
type: string
example: '30072'
guid:
type: string
example: 'plex://season/652aea6549508477c34c6000'
parentGuid:
type: string
example: 'plex://show/5d9c09190aaccd001f8f42f0'
parentStudio:
type: string
example: Amazon Studios
type:
type: string
example: season
title:
type: string
example: Season 2
parentKey:
type: string
example: /library/metadata/30072
parentTitle:
type: string
example: Reacher
summary:
type: string
example: 'Based on"Bad Luck and Trouble," when members of Reacher''s old military unit start turning up dead, Reacher has just one thing on his mind—revenge.'
index:
type: integer
format: int32
example: 2
parentIndex:
type: integer
format: int32
example: 1
viewCount:
type: integer
format: int32
example: 11
lastViewedAt:
type: integer
format: int32
example: 1705646565
parentYear:
type: integer
format: int32
example: 2022
thumb:
type: string
example: /library/metadata/66488/thumb/1703065033
art:
type: string
example: /library/metadata/30072/art/1705739923
parentThumb:
type: string
example: /library/metadata/30072/thumb/1705739923
parentTheme:
type: string
example: /library/metadata/30072/theme/1705739923
leafCount:
type: integer
format: int32
example: 8
viewedLeafCount:
type: integer
format: int32
example: 8
addedAt:
type: integer
format: int32
example: 1702602021
updatedAt:
type: integer
format: int32
example: 1703065033
userRating:
type: integer
format: int32
example: 9
skipCount:
type: integer
format: int32
example: 1
lastRatedAt:
type: integer
format: int32
example: 1703881224
example:
- ratingKey: '66488'
key: /library/metadata/66488/children
parentRatingKey: '30072'
guid: 'plex://season/652aea6549508477c34c6000'
parentGuid: 'plex://show/5d9c09190aaccd001f8f42f0'
parentStudio: Amazon Studios
type: season
title: Season 2
parentKey: /library/metadata/30072
parentTitle: Reacher
summary: 'Based on"Bad Luck and Trouble," when members of Reacher''s old military unit start turning up dead, Reacher has just one thing on his mind—revenge.'
index: 2
parentIndex: 1
viewCount: 11
lastViewedAt: 1705646565
parentYear: 2022
thumb: /library/metadata/66488/thumb/1703065033
art: /library/metadata/30072/art/1705739923
parentThumb: /library/metadata/30072/thumb/1705739923
parentTheme: /library/metadata/30072/theme/1705739923
leafCount: 8
viewedLeafCount: 8
addedAt: 1702602021
updatedAt: 1703065033
userRating: 9
skipCount: 1
lastRatedAt: 1703881224
'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
/library/onDeck:
get:
tags:
- Library
summary: Get On Deck
description: |
This endpoint will return the on deck content.
operationId: getOnDeck
responses:
'200':
description: The on Deck content
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 16
allowSync:
type: boolean
identifier:
type: string
example: com.plexapp.plugins.library
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: number
example: 1680021154
mixedParents:
type: boolean
Metadata:
type: array
items:
type: object
properties:
allowSync:
type: boolean
librarySectionID:
type: number
example: 2
librarySectionTitle:
type: string
example: TV Shows
librarySectionUUID:
type: string
example: 4bb2521c-8ba9-459b-aaee-8ab8bc35eabd
ratingKey:
type: number
example: 49564
key:
type: string
example: /library/metadata/49564
parentRatingKey:
type: number
example: 49557
grandparentRatingKey:
type: number
example: 49556
guid:
type: string
example: 'plex://episode/5ea7d7402e7ab10042e74d4f'
parentGuid:
type: string
example: 'plex://season/602e754d67f4c8002ce54b3d'
grandparentGuid:
type: string
example: 'plex://show/5d9c090e705e7a001e6e94d8'
type:
type: string
example: episode
title:
type: string
example: Circus
grandparentKey:
type: string
example: /library/metadata/49556
parentKey:
type: string
example: /library/metadata/49557
librarySectionKey:
type: string
example: /library/sections/2
grandparentTitle:
type: string
example: Bluey (2018)
parentTitle:
type: string
example: Season 2
contentRating:
type: string
example: TV-Y
summary:
type: string
example: Bluey is the ringmaster in a game of circus with her friends but Hercules wants to play his motorcycle game instead. Luckily Bluey has a solution to keep everyone happy.
index:
type: number
example: 33
parentIndex:
type: number
example: 2
lastViewedAt:
type: number
example: 1681908352
year:
type: number
example: 2018
thumb:
type: string
example: /library/metadata/49564/thumb/1654258204
art:
type: string
example: /library/metadata/49556/art/1680939546
parentThumb:
type: string
example: /library/metadata/49557/thumb/1654258204
grandparentThumb:
type: string
example: /library/metadata/49556/thumb/1680939546
grandparentArt:
type: string
example: /library/metadata/49556/art/1680939546
grandparentTheme:
type: string
example: /library/metadata/49556/theme/1680939546
duration:
type: number
example: 420080
originallyAvailableAt:
type: string
format: date-time
example: 2020-10-31T00:00:00.000Z
addedAt:
type: number
example: 1654258196
updatedAt:
type: number
example: 1654258204
Media:
type: array
items:
type: object
properties:
id:
type: number
example: 80994
duration:
type: number
example: 420080
bitrate:
type: number
example: 1046
width:
type: number
example: 1920
height:
type: number
example: 1080
aspectRatio:
type: number
example: 1.78
audioChannels:
type: number
example: 2
audioCodec:
type: string
example: aac
videoCodec:
type: string
example: hevc
videoResolution:
type: string
example: '1080'
container:
type: string
example: mkv
videoFrameRate:
type: string
example: PAL
audioProfile:
type: string
example: lc
videoProfile:
type: string
example: main
Part:
type: array
items:
type: object
properties:
id:
type: number
example: 80994
key:
type: string
example: /library/parts/80994/1655007810/file.mkv
duration:
type: number
example: 420080
file:
type: string
example: /tvshows/Bluey (2018)/Bluey (2018) - S02E33 - Circus.mkv
size:
type: number
example: 55148931
audioProfile:
type: string
example: lc
container:
type: string
example: mkv
videoProfile:
type: string
example: main
Stream:
type: array
items:
type: object
properties:
id:
type: number
example: 211234
streamType:
type: number
example: 1
default:
type: boolean
codec:
type: string
example: hevc
index:
type: number
example: 0
bitrate:
type: number
example: 918
language:
type: string
example: English
languageTag:
type: string
example: en
languageCode:
type: string
example: eng
bitDepth:
type: number
example: 8
chromaLocation:
type: string
example: left
chromaSubsampling:
type: string
example: '4:2:0'
codedHeight:
type: number
example: 1080
codedWidth:
type: number
example: 1920
colorRange:
type: string
example: tv
frameRate:
type: number
example: 25
height:
type: number
example: 1080
level:
type: number
example: 120
profile:
type: string
example: main
refFrames:
type: number
example: 1
width:
type: number
example: 1920
displayTitle:
type: string
example: 1080p (HEVC Main)
extendedDisplayTitle:
type: string
example: 1080p (HEVC Main)
Guid:
x-speakeasy-name-override: guids
type: array
items:
type: object
properties:
id:
type: string
example: 'imdb://tt13303712'
'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
/log:
get:
tags:
- Log
summary: Logging a single line message.
description: |
This endpoint will write a single-line log message, including a level and source to the main Plex Media Server log.
operationId: logLine
parameters:
- name: level
description: |
An integer log level to write to the PMS log with.
0: Error
1: Warning
2: Info
3: Debug
4: Verbose
in: query
schema:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
required: true
- name: message
description: The text of the message to write to the log.
in: query
schema:
type: string
example: Test log message
required: true
- name: source
description: a string indicating the source of the message.
in: query
schema:
type: string
example: Postman
required: true
responses:
'200':
description: Log Message Posted successfully
'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
post:
tags:
- Log
summary: Logging a multi-line message
description: |
This endpoint allows for the batch addition of log entries to the main Plex Media Server log.
It accepts a text/plain request body, where each line represents a distinct log entry.
Each log entry consists of URL-encoded key-value pairs, specifying log attributes such as 'level', 'message', and 'source'.
Log entries are separated by a newline character (`\n`).
Each entry's parameters should be URL-encoded to ensure accurate parsing and handling of special characters.
This method is efficient for logging multiple entries in a single API call, reducing the overhead of multiple individual requests.
The 'level' parameter specifies the log entry's severity or importance, with the following integer values:
- `0`: Error - Critical issues that require immediate attention.
- `1`: Warning - Important events that are not critical but may indicate potential issues.
- `2`: Info - General informational messages about system operation.
- `3`: Debug - Detailed information useful for debugging purposes.
- `4`: Verbose - Highly detailed diagnostic information for in-depth analysis.
The 'message' parameter contains the log text, and 'source' identifies the log message's origin (e.g., an application name or module).
Example of a single log entry format:
`level=4&message=Sample%20log%20entry&source=applicationName`
Ensure each parameter is properly URL-encoded to avoid interpretation issues.
operationId: logMultiLine
requestBody:
required: true
content:
text/plain:
schema:
type: string
example: |-
level=4&message=Test%20message%201&source=postman
level=3&message=Test%20message%202&source=postman
level=1&message=Test%20message%203&source=postman
responses:
'200':
description: Multi-Line Log Message Posted successfully
'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
/log/networked:
get:
tags:
- Log
summary: Enabling Papertrail
description: |
This endpoint will enable all Plex Media Serverlogs to be sent to the Papertrail networked logging site for a period of time.
operationId: enablePaperTrail
responses:
'200':
description: Papertrail enabled successfully
'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
'403':
description: the user was not signed in
/myplex/account:
get:
tags:
- Server
summary: Get MyPlex Account
description: Returns MyPlex Account Information
operationId: getMyPlexAccount
responses:
'200':
description: MyPlex Account
content:
application/json:
schema:
type: object
properties:
MyPlex:
type: object
properties:
authToken:
type: string
example: Z5v-PrNASDFpsaCi3CPK7
username:
type: string
example: example.email@mail.com
mappingState:
type: string
example: mapped
mappingError:
type: string
signInState:
type: string
example: ok
publicAddress:
type: string
example: 140.20.68.140
publicPort:
type: number
example: 32400
privateAddress:
type: string
example: 10.10.10.47
privatePort:
type: number
example: 32400
subscriptionFeatures:
type: string
example: 'federated-auth,hardware_transcoding,home,hwtranscode,item_clusters,kevin-bacon,livetv,loudness,lyrics,music-analysis,music_videos,pass,photo_autotags,photos-v5,photosV6-edit,photosV6-tv-albums,premium_music_metadata,radio,server-manager,session_bandwidth_restrictions,session_kick,shared-radio,sync,trailers,tuner-sharing,type-first,unsupportedtuners,webhooks'
subscriptionActive:
type: boolean
subscriptionState:
type: string
example: Active
'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
'/photo/:/transcode':
get:
tags:
- Server
summary: Get a Resized Photo
description: |
Plex's Photo transcoder is used throughout the service to serve images at specified sizes.
operationId: getResizedPhoto
parameters:
- name: width
description: The width for the resized photo
in: query
schema:
type: number
example: 110
required: true
- name: height
description: The height for the resized photo
in: query
schema:
type: number
example: 165
required: true
- name: opacity
description: The opacity for the resized photo
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 100
required: true
- name: blur
description: The width for the resized photo
in: query
schema:
type: number
examples:
- 0
- 20
- 4000
required: true
- name: minSize
description: images are always scaled proportionally. A value of '1' in minSize will make the smaller native dimension the dimension resized against.
in: query
schema:
type: integer
enum:
- 0
- 1
required: true
- name: upscale
description: allow images to be resized beyond native dimensions.
in: query
schema:
type: integer
enum:
- 0
- 1
required: true
- name: url
description: path to image within Plex
in: query
schema:
type: string
example: /library/metadata/49564/thumb/1654258204
required: true
responses:
'200':
description: Resized Image
'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:
servers:
- url: 'https://plex.tv/api/v2'
tags:
- Plex
summary: Get a Pin
operationId: getPin
description: Retrieve a Pin from Plex.tv for authentication flows
security: []
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
- name: X-Plex-Client-Identifier
description: |
The unique identifier for the client application
This is used to track the client application and its usage
(UUID, serial number, or other number unique per device)
in: header
schema:
type: string
required: true
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:
servers:
- url: 'https://plex.tv/api/v2'
tags:
- Plex
summary: Get Access Token
operationId: getToken
description: Retrieve an Access Token from Plex.tv after the Pin has already been authenticated
security: []
parameters:
- name: pinID
description: The PinID to retrieve an access token for
in: path
schema:
type: string
required: true
- name: X-Plex-Client-Identifier
description: |
The unique identifier for the client application
This is used to track the client application and its usage
(UUID, serial number, or other number unique per device)
in: header
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
/playlists:
post:
tags:
- Playlists
summary: Create a Playlist
description: |
Create a new playlist. By default the playlist is blank. To create a playlist along with a first item, pass:
- `uri` - The content URI for what we're playing (e.g. `server://1234/com.plexapp.plugins.library/library/metadata/1`).
- `playQueueID` - To create a playlist from an existing play queue.
operationId: createPlaylist
parameters:
- name: title
description: name of the playlist
in: query
schema:
type: string
required: true
- name: type
description: type of playlist to create
in: query
schema:
type: string
enum:
- audio
- video
- photo
required: true
- name: smart
description: whether the playlist is smart or not
in: query
schema:
type: integer
enum:
- 0
- 1
required: true
- name: uri
description: the content URI for the playlist
in: query
schema:
type: string
required: true
- name: playQueueID
description: the play queue to copy to a playlist
in: query
schema:
type: number
required: false
responses:
'200':
description: returns all playlists
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 7
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '96'
key:
type: string
example: /playlists/96/items
guid:
type: string
example: 'com.plexapp.agents.none://a2f92937-1408-40e2-b022-63a8a9377e55'
type:
type: string
example: playlist
title:
type: string
example: A Great Playlist
summary:
type: string
example: What a great playlist
smart:
type: boolean
example: false
playlistType:
type: string
example: video
icon:
type: string
example: 'playlist://image.smart'
viewCount:
type: integer
format: int32
example: 1
lastViewedAt:
type: integer
format: int32
example: 1705719589
leafCount:
type: integer
format: int32
example: 1
addedAt:
type: integer
format: int32
example: 1705719589
updatedAt:
type: integer
format: int32
example: 1705724593
composite:
type: string
example: /playlists/96/composite/1705724593
duration:
type: integer
format: int32
example: 141000
example:
- ratingKey: '96'
key: /playlists/96/items
guid: 'com.plexapp.agents.none://a2f92937-1408-40e2-b022-63a8a9377e55'
type: playlist
title: A Great Playlist
summary: What a great playlist
smart: false
playlistType: video
icon: 'playlist://image.smart'
viewCount: 1
lastViewedAt: 1705719589
leafCount: 1
addedAt: 1705719589
updatedAt: 1705724593
composite: /playlists/96/composite/1705724593
duration: 141000
'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
get:
tags:
- Playlists
summary: Get All Playlists
description: Get All Playlists given the specified filters.
operationId: getPlaylists
parameters:
- name: playlistType
description: limit to a type of playlist.
in: query
schema:
type: string
enum:
- audio
- video
- photo
required: false
- name: smart
description: type of playlists to return (default is all).
in: query
schema:
type: integer
enum:
- 0
- 1
required: false
responses:
'200':
description: returns all playlists
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 4
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '92'
key:
type: string
example: /playlists/92/items
guid:
type: string
example: 'com.plexapp.agents.none://7ca5aaef-58e8-4828-9e21-c009c97f2903'
type:
type: string
example: playlist
title:
type: string
example: Static Playlist
summary:
type: string
example: A Great Playlist
smart:
type: boolean
example: false
playlistType:
type: string
example: video
composite:
type: string
example: /playlists/92/composite/1705716440
icon:
type: string
example: 'playlist://image.smart'
viewCount:
type: integer
format: int32
example: 1
lastViewedAt:
type: integer
format: int32
example: 1705716298
duration:
type: integer
format: int32
example: 7328000
leafCount:
type: integer
format: int32
example: 32
addedAt:
type: integer
format: int32
example: 1705716298
updatedAt:
type: integer
format: int32
example: 1705716440
example:
- ratingKey: '92'
key: /playlists/92/items
guid: 'com.plexapp.agents.none://7ca5aaef-58e8-4828-9e21-c009c97f2903'
type: playlist
title: Static Playlist
summary: A Great Playlist
smart: false
playlistType: video
composite: /playlists/92/composite/1705716440
icon: 'playlist://image.smart'
viewCount: 1
lastViewedAt: 1705716298
duration: 7328000
leafCount: 32
addedAt: 1705716298
updatedAt: 1705716440
'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
'/playlists/{playlistID}':
get:
tags:
- Playlists
summary: Retrieve Playlist
description: |
Gets detailed metadata for a playlist. A playlist for many purposes (rating, editing metadata, tagging), can be treated like a regular metadata item:
Smart playlist details contain the `content` attribute. This is the content URI for the generator. This can then be parsed by a client to provide smart playlist editing.
operationId: getPlaylist
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
responses:
'200':
description: The playlist
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
Metadata:
type: array
items:
type: object
properties:
content:
type: string
example: 'library://x/directory/%2Flibrary%2Fsections%2F1%2Fall%3Ftype%3D1%26push%3D1%26title%3D2%26or%3D1%26title%3DSerenity%26pop%3D1'
ratingKey:
type: string
example: '95'
key:
type: string
example: /playlists/95/items
guid:
type: string
example: 'com.plexapp.agents.none://87425529-380f-44b8-a689-9a0537e7ec91'
type:
type: string
example: playlist
title:
type: string
example: Smart Movie Playlist
summary:
type: string
example: ''
smart:
type: boolean
example: true
playlistType:
type: string
example: video
composite:
type: string
example: /playlists/95/composite/1705717387
icon:
type: string
example: 'playlist://image.smart'
duration:
type: integer
format: int32
example: 282000
leafCount:
type: integer
format: int32
example: 2
addedAt:
type: integer
format: int32
example: 1705716493
updatedAt:
type: integer
format: int32
example: 1705717387
example:
- content: 'library://x/directory/%2Flibrary%2Fsections%2F1%2Fall%3Ftype%3D1%26push%3D1%26title%3D2%26or%3D1%26title%3DSerenity%26pop%3D1'
ratingKey: '95'
key: /playlists/95/items
guid: 'com.plexapp.agents.none://87425529-380f-44b8-a689-9a0537e7ec91'
type: playlist
title: Smart Movie Playlist
summary: ''
smart: true
playlistType: video
composite: /playlists/95/composite/1705717387
icon: 'playlist://image.smart'
duration: 282000
leafCount: 2
addedAt: 1705716493
updatedAt: 1705717387
'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
delete:
tags:
- Playlists
summary: Deletes a Playlist
description: |
This endpoint will delete a playlist
operationId: deletePlaylist
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
responses:
'200':
description: The playlist is deleted
'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
put:
tags:
- Playlists
summary: Update a Playlist
description: |
From PMS version 1.9.1 clients can also edit playlist metadata using this endpoint as they would via `PUT /library/metadata/{playlistID}`
operationId: updatePlaylist
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
- name: title
description: name of the playlist
in: query
schema:
type: string
required: false
- name: summary
description: summary description of the playlist
in: query
schema:
type: string
required: false
responses:
'200':
description: The playlist is deleted
'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
'/playlists/{playlistID}/items':
get:
tags:
- Playlists
summary: Retrieve Playlist Contents
description: |
Gets the contents of a playlist. Should be paged by clients via standard mechanisms.
By default leaves are returned (e.g. episodes, movies). In order to return other types you can use the `type` parameter.
For example, you could use this to display a list of recently added albums vis a smart playlist.
Note that for dumb playlists, items have a `playlistItemID` attribute which is used for deleting or moving items.
operationId: getPlaylistContents
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
- name: type
description: the metadata type of the item to return
in: query
schema:
type: number
required: true
responses:
'200':
description: The playlist contents
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 2
composite:
type: string
example: /playlists/95/composite/1705717521
duration:
type: integer
format: int32
example: 282
leafCount:
type: integer
format: int32
example: 2
playlistType:
type: string
example: video
ratingKey:
type: string
example: '95'
smart:
type: boolean
example: true
title:
type: string
example: Smart Movie Playlist
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '17'
key:
type: string
example: /library/metadata/17
guid:
type: string
example: 'plex://movie/5d77683f6f4521001ea9dc53'
studio:
type: string
example: Universal Pictures
type:
type: string
example: movie
title:
type: string
example: Serenity
titleSort:
type: string
example: Amazing Spider-Man 2
librarySectionTitle:
type: string
example: Movies
librarySectionID:
type: integer
format: int32
example: 1
librarySectionKey:
type: string
example: /library/sections/1
contentRating:
type: string
example: PG-13
summary:
type: string
example: 'Serenity continues the story of the TV series it was based upon ("Firefly"). River Tam had a secret - one in which she''s not even aware - so dangerous, no one''s safe, as an Alliance operative''s sent to capture her, and all others are considered irrelevant to his job.'
rating:
type: number
example: 8.2
audienceRating:
type: number
example: 9.1
year:
type: integer
format: int32
example: 2005
tagline:
type: string
example: They aim to misbehave.
thumb:
type: string
example: /library/metadata/17/thumb/1705637165
art:
type: string
example: /library/metadata/17/art/1705637165
duration:
type: integer
format: int32
example: 141416
originallyAvailableAt:
type: string
format: date
example: 2005-09-29T00:00:00.000Z
addedAt:
type: integer
format: int32
example: 1705637164
updatedAt:
type: integer
format: int32
example: 1705637165
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
hasPremiumExtras:
type: string
example: '1'
hasPremiumPrimaryExtra:
type: string
example: '1'
ratingImage:
type: string
example: 'rottentomatoes://image.rating.ripe'
Media:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 15
duration:
type: integer
format: int32
example: 141416
bitrate:
type: integer
format: int32
example: 2273
width:
type: integer
format: int32
example: 1920
height:
type: integer
format: int32
example: 814
aspectRatio:
type: number
example: 2.35
audioChannels:
type: integer
format: int32
example: 2
audioCodec:
type: string
example: aac
videoCodec:
type: string
example: h264
videoResolution:
type: string
example: '1080'
container:
type: string
example: mp4
videoFrameRate:
type: string
example: 24p
optimizedForStreaming:
type: integer
format: int32
example: 0
audioProfile:
type: string
example: lc
has64bitOffsets:
type: boolean
example: false
videoProfile:
type: string
example: high
Part:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 15
key:
type: string
example: /library/parts/15/1705637151/file.mp4
duration:
type: integer
format: int32
example: 141416
file:
type: string
example: /movies/Serenity (2005)/Serenity (2005).mp4
size:
type: integer
format: int32
example: 40271948
audioProfile:
type: string
example: lc
container:
type: string
example: mp4
has64bitOffsets:
type: boolean
example: false
optimizedForStreaming:
type: boolean
example: false
videoProfile:
type: string
example: high
example:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141416
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
example:
- id: 15
duration: 141416
bitrate: 2273
width: 1920
height: 814
aspectRatio: 2.35
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 0
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141416
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Genre:
type: array
items:
type: object
properties:
tag:
type: string
example: Action
example:
- tag: Action
Country:
type: array
items:
type: object
properties:
tag:
type: string
example: United States of America
example:
- tag: United States of America
Director:
type: array
items:
type: object
properties:
tag:
type: string
example: Joss Whedon
example:
- tag: Joss Whedon
Writer:
type: array
items:
type: object
properties:
tag:
type: string
example: Joss Whedon
example:
- tag: Joss Whedon
Role:
type: array
items:
type: object
properties:
tag:
type: string
example: Gina Torres
example:
- tag: Gina Torres
example:
- ratingKey: '17'
key: /library/metadata/17
guid: 'plex://movie/5d77683f6f4521001ea9dc53'
studio: Universal Pictures
type: movie
title: Serenity
titleSort: Amazing Spider-Man 2
librarySectionTitle: Movies
librarySectionID: 1
librarySectionKey: /library/sections/1
contentRating: PG-13
summary: 'Serenity continues the story of the TV series it was based upon ("Firefly"). River Tam had a secret - one in which she''s not even aware - so dangerous, no one''s safe, as an Alliance operative''s sent to capture her, and all others are considered irrelevant to his job.'
rating: 8.2
audienceRating: 9.1
year: 2005
tagline: They aim to misbehave.
thumb: /library/metadata/17/thumb/1705637165
art: /library/metadata/17/art/1705637165
duration: 141416
originallyAvailableAt: 2005-09-29T00:00:00.000Z
addedAt: 1705637164
updatedAt: 1705637165
audienceRatingImage: 'rottentomatoes://image.rating.upright'
hasPremiumExtras: '1'
hasPremiumPrimaryExtra: '1'
ratingImage: 'rottentomatoes://image.rating.ripe'
Media:
- id: 15
duration: 141416
bitrate: 2273
width: 1920
height: 814
aspectRatio: 2.35
audioChannels: 2
audioCodec: aac
videoCodec: h264
videoResolution: '1080'
container: mp4
videoFrameRate: 24p
optimizedForStreaming: 0
audioProfile: lc
has64bitOffsets: false
videoProfile: high
Part:
- id: 15
key: /library/parts/15/1705637151/file.mp4
duration: 141416
file: /movies/Serenity (2005)/Serenity (2005).mp4
size: 40271948
audioProfile: lc
container: mp4
has64bitOffsets: false
optimizedForStreaming: false
videoProfile: high
Genre:
- tag: Science Fiction
Country:
- tag: United States of America
Director:
- tag: Joss Whedon
Writer:
- tag: Joss Whedon
Role:
- tag: Nathan Fillion
'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
delete:
tags:
- Playlists
summary: Delete Playlist Contents
description: |
Clears a playlist, only works with dumb playlists. Returns the playlist.
operationId: clearPlaylistContents
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
responses:
'200':
description: The playlist contents are cleared
'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
put:
tags:
- Playlists
summary: Adding to a Playlist
description: |
Adds a generator to a playlist, same parameters as the POST to create. With a dumb playlist, this adds the specified items to the playlist.
With a smart playlist, passing a new `uri` parameter replaces the rules for the playlist. Returns the playlist.
operationId: addPlaylistContents
parameters:
- name: playlistID
description: the ID of the playlist
in: path
schema:
type: number
required: true
- name: uri
description: the content URI for the playlist
in: query
schema:
type: string
example: 'server://12345/com.plexapp.plugins.library/library/metadata/1'
required: true
- name: playQueueID
description: the play queue to add to a playlist
in: query
schema:
type: number
example: 123
required: false
responses:
'200':
description: Playlist Updated
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
leafCountAdded:
type: integer
format: int32
example: 1
leafCountRequested:
type: integer
format: int32
example: 1
Metadata:
type: array
items:
type: object
properties:
ratingKey:
type: string
example: '94'
key:
type: string
example: /playlists/94/items
guid:
type: string
example: 'com.plexapp.agents.none://972e3047-83d6-4848-a000-261f0af26ba2'
type:
type: string
example: playlist
title:
type: string
example: A great playlist
summary:
type: string
example: One of my great playlists
smart:
type: boolean
example: false
playlistType:
type: string
example: video
composite:
type: string
example: /playlists/94/composite/1705800070
duration:
type: integer
format: int32
example: 423000
leafCount:
type: integer
format: int32
example: 3
addedAt:
type: integer
format: int32
example: 1705716458
updatedAt:
type: integer
format: int32
example: 1705800070
example:
- ratingKey: '94'
key: /playlists/94/items
guid: 'com.plexapp.agents.none://972e3047-83d6-4848-a000-261f0af26ba2'
type: playlist
title: A great playlist
summary: One of my great playlists
smart: false
playlistType: video
composite: /playlists/94/composite/1705800070
duration: 423000
leafCount: 3
addedAt: 1705716458
updatedAt: 1705800070
'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
/playlists/upload:
post:
tags:
- Playlists
summary: Upload Playlist
description: |
Imports m3u playlists by passing a path on the server to scan for m3u-formatted playlist files, or a path to a single playlist file.
operationId: uploadPlaylist
parameters:
- name: path
description: |
absolute path to a directory on the server where m3u files are stored, or the absolute path to a playlist file on the server.
If the `path` argument is a directory, that path will be scanned for playlist files to be processed.
Each file in that directory creates a separate playlist, with a name based on the filename of the file that created it.
The GUID of each playlist is based on the filename.
If the `path` argument is a file, that file will be used to create a new playlist, with the name based on the filename of the file that created it.
The GUID of each playlist is based on the filename.
in: query
schema:
type: string
example: /home/barkley/playlist.m3u
required: true
- name: force
description: |
Force overwriting of duplicate playlists.
By default, a playlist file uploaded with the same path will overwrite the existing playlist.
The `force` argument is used to disable overwriting.
If the `force` argument is set to 0, a new playlist will be created suffixed with the date and time that the duplicate was uploaded.
in: query
schema:
type: integer
enum:
- 0
- 1
required: true
responses:
'200':
description: The playlist is uploaded
'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
/search:
get:
tags:
- Search
summary: Get Search Results
description: This will search the database for the string provided.
operationId: getSearchResults
parameters:
- name: query
description: The search query string to use
in: query
schema:
type: string
example: '110'
required: true
responses:
'200':
description: Search Results
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 26
identifier:
type: string
example: com.plexapp.plugins.library
mediaTagPrefix:
type: string
example: /system/bundle/media/flags/
mediaTagVersion:
type: number
example: 1680021154
Metadata:
type: array
items:
type: object
properties:
allowSync:
type: boolean
librarySectionID:
type: number
example: 1
librarySectionTitle:
type: string
example: Movies
librarySectionUUID:
type: string
example: 322a231a-b7f7-49f5-920f-14c61199cd30
personal:
type: boolean
sourceTitle:
type: string
example: Hera
ratingKey:
type: number
example: 10398
key:
type: string
example: /library/metadata/10398
guid:
type: string
example: 'plex://movie/5d7768284de0ee001fcc8f52'
studio:
type: string
example: Paramount
type:
type: string
example: movie
title:
type: string
example: 'Mission: Impossible'
contentRating:
type: string
example: PG-13
summary:
type: string
example: When Ethan Hunt the leader of a crack espionage team whose perilous operation has gone awry with no explanation discovers that a mole has penetrated the CIA he's surprised to learn that he's the No. 1 suspect. To clear his name Hunt now must ferret out the real double agent and in the process even the score.
rating:
type: number
example: 6.6
audienceRating:
type: number
example: 7.1
year:
type: number
example: 1996
tagline:
type: string
example: Expect the impossible.
thumb:
type: string
example: /library/metadata/10398/thumb/1679505055
art:
type: string
example: /library/metadata/10398/art/1679505055
duration:
type: number
example: 6612628
originallyAvailableAt:
type: string
format: date-time
example: 1996-05-22T00:00:00.000Z
addedAt:
type: number
example: 1589234571
updatedAt:
type: number
example: 1679505055
audienceRatingImage:
type: string
example: 'rottentomatoes://image.rating.upright'
chapterSource:
type: string
example: media
primaryExtraKey:
type: string
example: /library/metadata/10501
ratingImage:
type: string
example: 'rottentomatoes://image.rating.ripe'
Media:
type: array
items:
type: object
properties:
id:
type: number
example: 26610
duration:
type: number
example: 6612628
bitrate:
type: number
example: 4751
width:
type: number
example: 1916
height:
type: number
example: 796
aspectRatio:
type: number
example: 2.35
audioChannels:
type: number
example: 6
audioCodec:
type: string
example: aac
videoCodec:
type: string
example: hevc
videoResolution:
type: number
example: 1080
container:
type: string
example: mkv
videoFrameRate:
type: string
example: 24p
audioProfile:
type: string
example: lc
videoProfile:
type: string
example: main 10
Part:
type: array
items:
type: object
properties:
id:
type: number
example: 26610
key:
type: string
example: /library/parts/26610/1589234571/file.mkv
duration:
type: number
example: 6612628
file:
type: string
example: /movies/Mission Impossible (1996)/Mission Impossible (1996) Bluray-1080p.mkv
size:
type: number
example: 3926903851
audioProfile:
type: string
example: lc
container:
type: string
example: mkv
videoProfile:
type: string
example: main 10
Genre:
type: array
items:
type: object
properties:
tag:
type: string
example: Action
Director:
type: array
items:
type: object
properties:
tag:
type: string
example: Brian De Palma
Writer:
type: array
items:
type: object
properties:
tag:
type: string
example: David Koepp
Country:
type: array
items:
type: object
properties:
tag:
type: string
example: United States of America
Role:
type: array
items:
type: object
properties:
tag:
type: string
example: Tom Cruise
Provider:
type: array
items:
type: object
properties:
key:
type: string
example: /system/search
title:
type: string
example: Local Network
type:
type: string
example: mixed
'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
/security/token:
get:
tags:
- Security
summary: Get a Transient Token.
description: |
This endpoint provides the caller with a temporary token with the same access level as the caller's token. These tokens are valid for up to 48 hours and are destroyed if the server instance is restarted.
operationId: getTransientToken
parameters:
- name: type
description: '`delegation` - This is the only supported `type` parameter.'
in: query
schema:
type: string
enum:
- delegation
required: true
- name: scope
description: '`all` - This is the only supported `scope` parameter.'
in: query
schema:
type: string
enum:
- all
required: true
responses:
'200':
description: A Transient Token
'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
/security/resources:
get:
tags:
- Security
summary: Get Source Connection Information
description: |
If a caller requires connection details and a transient token for a source that is known to the server, for example a cloud media provider or shared PMS, then this endpoint can be called. This endpoint is only accessible with either an admin token or a valid transient token generated from an admin token.
Note: requires Plex Media Server >= 1.15.4.
operationId: getSourceConnectionInformation
parameters:
- name: source
description: The source identifier with an included prefix.
in: query
schema:
type: string
examples:
- 'server://client-identifier'
- 'provider://provider-identifier'
required: true
responses:
'200':
description: Source Connection Information
'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
/servers:
get:
tags:
- Server
summary: Get Server List
description: Get Server List
operationId: getServerList
responses:
'200':
description: List of Servers
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: number
example: 1
Server:
type: array
items:
type: object
properties:
name:
type: string
example: Hera
host:
type: string
example: 10.10.10.47
address:
type: string
example: 10.10.10.47
port:
type: number
example: 32400
machineIdentifier:
type: string
example: 96f2fe7a78c9dc1f16a16bedbe90f98149be16b4
version:
type: string
example: 1.31.3.6868-28fc46b27
'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
/statistics/media:
get:
tags:
- Statistics
summary: Get Media Statistics
description: This will return the media statistics for the server
operationId: getStatistics
parameters:
- name: Timespan
description: |
The timespan to retrieve statistics for
the exact meaning of this parameter is not known
in: query
required: false
example: 4
responses:
'200':
description: Media Statistics
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 5497
Device:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 208
name:
type: string
example: Roku Express
platform:
type: string
example: Roku
clientIdentifier:
type: string
example: 793095d235660625108ef785cc7646e9
createdAt:
type: integer
format: int32
example: 1706470556
example:
- id: 208
name: Roku Express
platform: Roku
clientIdentifier: 793095d235660625108ef785cc7646e9
createdAt: 1706470556
Account:
type: array
items:
type: object
properties:
id:
type: integer
format: int32
example: 238960586
key:
type: string
example: /accounts/238960586
name:
type: string
example: Diane
defaultAudioLanguage:
type: string
example: en
autoSelectAudio:
type: boolean
example: true
defaultSubtitleLanguage:
type: string
example: en
subtitleMode:
type: integer
format: int32
example: 1
thumb:
type: string
example: 'https://plex.tv/users/50d83634246da1de/avatar?c=1707110967'
example:
- id: 238960586
key: /accounts/238960586
name: Diane
defaultAudioLanguage: en
autoSelectAudio: true
defaultSubtitleLanguage: en
subtitleMode: 1
thumb: 'https://plex.tv/users/50d83634246da1de/avatar?c=1707110967'
StatisticsMedia:
type: array
items:
type: object
properties:
accountID:
type: integer
format: int32
example: 1
deviceID:
type: integer
format: int32
example: 13
timespan:
type: integer
format: int32
example: 4
at:
type: integer
format: int32
example: 1707141600
metadataType:
type: integer
format: int32
example: 4
count:
type: integer
format: int32
example: 1
duration:
type: integer
format: int32
example: 1555
example:
- accountID: 1
deviceID: 13
timespan: 4
at: 1707141600
metadataType: 4
count: 1
duration: 1555
'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
/status/sessions:
get:
tags:
- Sessions
summary: Get Active Sessions
description: This will retrieve the "Now Playing" Information of the PMS.
operationId: getSessions
responses:
'200':
description: List of Active Plex Sessions
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
Metadata:
type: array
items:
type: object
properties:
addedAt:
type: integer
format: int32
example: 1705543312
art:
type: string
example: /library/metadata/39904/art/1705310687
duration:
type: integer
format: int32
example: 186240
grandparentArt:
type: string
example: /library/metadata/39904/art/1705310687
grandparentGuid:
type: string
example: 'plex://artist/5d07bbfd403c6402904a6480'
grandparentKey:
type: string
example: /library/metadata/39904
grandparentRatingKey:
type: string
example: '39904'
grandparentThumb:
type: string
example: /library/metadata/39904/thumb/1705310687
grandparentTitle:
type: string
example: Green Day
guid:
type: string
example: 'plex://track/6535834f71f22f36f71a8e8f'
index:
type: integer
format: int32
example: 1
key:
type: string
example: /library/metadata/67085
librarySectionID:
type: string
example: '3'
librarySectionKey:
type: string
example: /library/sections/3
librarySectionTitle:
type: string
example: Music
musicAnalysisVersion:
type: string
example: '1'
parentGuid:
type: string
example: 'plex://album/65394d6d472b8ab03ef47f12'
parentIndex:
type: integer
format: int32
example: 1
parentKey:
type: string
example: /library/metadata/67084
parentRatingKey:
type: string
example: '67084'
parentStudio:
type: string
example: Reprise Records
parentThumb:
type: string
example: /library/metadata/67084/thumb/1705543314
parentTitle:
type: string
example: Saviors
parentYear:
type: integer
format: int32
example: 2024
ratingCount:
type: integer
format: int32
example: 45885
ratingKey:
type: string
example: '67085'
sessionKey:
type: string
example: '203'
thumb:
type: string
example: /library/metadata/67084/thumb/1705543314
title:
type: string
example: The American Dream Is Killing Me
titleSort:
type: string
example: American Dream Is Killing Me
type:
type: string
example: track
updatedAt:
type: integer
format: int32
example: 1705543314
viewOffset:
type: integer
format: int32
example: 1000
Media:
type: array
items:
type: object
properties:
audioChannels:
type: integer
format: int32
example: 2
audioCodec:
type: string
example: flac
bitrate:
type: integer
format: int32
example: 1014
container:
type: string
example: flac
duration:
type: integer
format: int32
example: 186240
id:
type: string
example: '130355'
selected:
type: boolean
example: true
Part:
type: array
items:
type: object
properties:
container:
type: string
example: flac
duration:
type: integer
format: int32
example: 186240
file:
type: string
example: /music/Green Day/Saviors (2024)/Green Day - Saviors - 01 - The American Dream Is Killing Me.flac
hasThumbnail:
type: string
example: '1'
id:
type: string
example: '130625'
key:
type: string
example: /library/parts/130625/1705543268/file.flac
size:
type: integer
format: int32
example: 23644000
decision:
type: string
example: directplay
selected:
type: boolean
example: true
Stream:
type: array
items:
type: object
properties:
albumGain:
type: string
example: '-12.94'
albumPeak:
type: string
example: '1.000000'
albumRange:
type: string
example: '4.751014'
audioChannelLayout:
type: string
example: stereo
bitDepth:
type: integer
format: int32
example: 16
bitrate:
type: integer
format: int32
example: 1014
channels:
type: integer
format: int32
example: 2
codec:
type: string
example: flac
displayTitle:
type: string
example: FLAC (Stereo)
extendedDisplayTitle:
type: string
example: FLAC (Stereo)
gain:
type: string
example: '-12.94'
id:
type: string
example: '352487'
index:
type: integer
format: int32
example: 0
loudness:
type: string
example: '-5.94'
lra:
type: string
example: '1.74'
peak:
type: string
example: '1.000000'
samplingRate:
type: integer
format: int32
example: 44100
selected:
type: boolean
example: true
streamType:
type: integer
format: int32
example: 2
location:
type: string
example: direct
example:
- albumGain: '-12.94'
albumPeak: '1.000000'
albumRange: '4.751014'
audioChannelLayout: stereo
bitDepth: 16
bitrate: 1014
channels: 2
codec: flac
displayTitle: FLAC (Stereo)
extendedDisplayTitle: FLAC (Stereo)
gain: '-12.94'
id: '352487'
index: 0
loudness: '-5.94'
lra: '1.74'
peak: '1.000000'
samplingRate: 44100
selected: true
streamType: 2
location: direct
example:
- container: flac
duration: 186240
file: /music/Green Day/Saviors (2024)/Green Day - Saviors - 01 - The American Dream Is Killing Me.flac
hasThumbnail: '1'
id: '130625'
key: /library/parts/130625/1705543268/file.flac
size: 23644000
decision: directplay
selected: true
Stream:
- albumGain: '-12.94'
albumPeak: '1.000000'
albumRange: '4.751014'
audioChannelLayout: stereo
bitDepth: 16
bitrate: 1014
channels: 2
codec: flac
displayTitle: FLAC (Stereo)
extendedDisplayTitle: FLAC (Stereo)
gain: '-12.94'
id: '352487'
index: 0
loudness: '-5.94'
lra: '1.74'
peak: '1.000000'
samplingRate: 44100
selected: true
streamType: 2
location: direct
example:
- audioChannels: 2
audioCodec: flac
bitrate: 1014
container: flac
duration: 186240
id: '130355'
selected: true
Part:
- container: flac
duration: 186240
file: /music/Green Day/Saviors (2024)/Green Day - Saviors - 01 - The American Dream Is Killing Me.flac
hasThumbnail: '1'
id: '130625'
key: /library/parts/130625/1705543268/file.flac
size: 23644000
decision: directplay
selected: true
Stream:
- albumGain: '-12.94'
albumPeak: '1.000000'
albumRange: '4.751014'
audioChannelLayout: stereo
bitDepth: 16
bitrate: 1014
channels: 2
codec: flac
displayTitle: FLAC (Stereo)
extendedDisplayTitle: FLAC (Stereo)
gain: '-12.94'
id: '352487'
index: 0
loudness: '-5.94'
lra: '1.74'
peak: '1.000000'
samplingRate: 44100
selected: true
streamType: 2
location: direct
User:
type: object
properties:
id:
type: string
example: '1'
thumb:
type: string
example: 'https://plex.tv/users/844780fc6f8a26b5/avatar?c=1705853661'
title:
type: string
example: Blindkitty38
Player:
type: object
properties:
address:
type: string
example: 10.10.10.171
machineIdentifier:
type: string
example: 3tsdzir85m2onc3qyr255aq1
model:
type: string
example: standalone
platform:
type: string
example: windows
platformVersion:
type: string
example: 10.0.22621
product:
type: string
example: Plex for Windows
profile:
type: string
example: Plex Desktop
remotePublicAddress:
type: string
example: 68.248.140.20
state:
type: string
example: playing
title:
type: string
example: DESKTOP-BL80MTD
version:
type: string
example: 1.85.0.4071-21128b56
local:
type: boolean
example: true
relayed:
type: boolean
example: false
secure:
type: boolean
example: true
userID:
type: integer
format: int32
example: 1
Session:
type: object
properties:
id:
type: string
example: 93h7e00ncblxncqw9lkfaoxi
bandwidth:
type: integer
format: int32
example: 1050
location:
type: string
example: lan
example:
- addedAt: 1705543312
art: /library/metadata/39904/art/1705310687
duration: 186240
grandparentArt: /library/metadata/39904/art/1705310687
grandparentGuid: 'plex://artist/5d07bbfd403c6402904a6480'
grandparentKey: /library/metadata/39904
grandparentRatingKey: '39904'
grandparentThumb: /library/metadata/39904/thumb/1705310687
grandparentTitle: Green Day
guid: 'plex://track/6535834f71f22f36f71a8e8f'
index: 1
key: /library/metadata/67085
librarySectionID: '3'
librarySectionKey: /library/sections/3
librarySectionTitle: Music
musicAnalysisVersion: '1'
parentGuid: 'plex://album/65394d6d472b8ab03ef47f12'
parentIndex: 1
parentKey: /library/metadata/67084
parentRatingKey: '67084'
parentStudio: Reprise Records
parentThumb: /library/metadata/67084/thumb/1705543314
parentTitle: Saviors
parentYear: 2024
ratingCount: 45885
ratingKey: '67085'
sessionKey: '203'
thumb: /library/metadata/67084/thumb/1705543314
title: The American Dream Is Killing Me
titleSort: American Dream Is Killing Me
type: track
updatedAt: 1705543314
viewOffset: 1000
Media:
- audioChannels: 2
audioCodec: flac
bitrate: 1014
container: flac
duration: 186240
id: '130355'
selected: true
Part:
- container: flac
duration: 186240
file: /music/Green Day/Saviors (2024)/Green Day - Saviors - 01 - The American Dream Is Killing Me.flac
hasThumbnail: '1'
id: '130625'
key: /library/parts/130625/1705543268/file.flac
size: 23644000
decision: directplay
selected: true
Stream:
- albumGain: '-12.94'
albumPeak: '1.000000'
albumRange: '4.751014'
audioChannelLayout: stereo
bitDepth: 16
bitrate: 1014
channels: 2
codec: flac
displayTitle: FLAC (Stereo)
extendedDisplayTitle: FLAC (Stereo)
gain: '-12.94'
id: '352487'
index: 0
loudness: '-5.94'
lra: '1.74'
peak: '1.000000'
samplingRate: 44100
selected: true
streamType: 2
location: direct
User:
id: '1'
thumb: 'https://plex.tv/users/844780fc6f8a26b5/avatar?c=1705853661'
title: Blindkitty38
Player:
address: 10.10.10.171
machineIdentifier: 3tsdzir85m2onc3qyr255aq1
model: standalone
platform: windows
platformVersion: 10.0.22621
product: Plex for Windows
profile: Plex Desktop
remotePublicAddress: 68.248.140.20
state: playing
title: DESKTOP-BL80MTD
version: 1.85.0.4071-21128b56
local: true
relayed: false
secure: true
userID: 1
Session:
id: 93h7e00ncblxncqw9lkfaoxi
bandwidth: 1050
location: lan
'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
/status/sessions/history/all:
get:
tags:
- Sessions
summary: Get Session History
description: This will Retrieve a listing of all history views.
operationId: getSessionHistory
responses:
'200':
description: List of Plex Sessions
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 10855
Metadata:
type: array
items:
type: object
properties:
historyKey:
type: string
example: /status/sessions/history/1
key:
type: string
example: /library/metadata/32171
ratingKey:
type: string
example: '32171'
librarySectionID:
type: string
example: '2'
parentKey:
type: string
example: /library/metadata/32170
grandparentKey:
type: string
example: /library/metadata/32132
title:
type: string
example: The Noise That Blue Makes
grandparentTitle:
type: string
example: Taskmaster
type:
type: string
example: episode
thumb:
type: string
example: /library/metadata/32171/thumb/-1
parentThumb:
type: string
example: /library/metadata/32170/thumb/1654134301
grandparentThumb:
type: string
example: /library/metadata/32132/thumb/1703933346
grandparentArt:
type: string
example: /library/metadata/32132/art/1703933346
index:
type: integer
format: int32
example: 1
parentIndex:
type: integer
format: int32
example: 13
originallyAvailableAt:
type: string
format: date
example: 2022-04-14T00:00:00.000Z
viewedAt:
type: integer
format: int32
example: 1654139223
accountID:
type: integer
format: int32
example: 1
deviceID:
type: integer
format: int32
example: 5
example:
- historyKey: /status/sessions/history/1
key: /library/metadata/32171
ratingKey: '32171'
librarySectionID: '2'
parentKey: /library/metadata/32170
grandparentKey: /library/metadata/32132
title: The Noise That Blue Makes
grandparentTitle: Taskmaster
type: episode
thumb: /library/metadata/32171/thumb/-1
parentThumb: /library/metadata/32170/thumb/1654134301
grandparentThumb: /library/metadata/32132/thumb/1703933346
grandparentArt: /library/metadata/32132/art/1703933346
index: 1
parentIndex: 13
originallyAvailableAt: 2022-04-14T00:00:00.000Z
viewedAt: 1654139223
accountID: 1
deviceID: 5
'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
/transcode/sessions:
get:
tags:
- Sessions
summary: Get Transcode Sessions
description: Get Transcode Sessions
operationId: getTranscodeSessions
responses:
'200':
description: The Transcode Sessions
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
TranscodeSession:
type: array
items:
type: object
properties:
key:
type: string
example: vv3i2q2lax92qlzul1hbd4bx
throttled:
type: boolean
example: false
complete:
type: boolean
example: false
progress:
type: number
example: 1.7999999523162842
size:
type: integer
format: int32
example: -22
speed:
type: number
example: 25.100000381469727
error:
type: boolean
example: false
duration:
type: integer
format: int32
example: 1445695
remaining:
type: integer
format: int32
example: 53
context:
type: string
example: streaming
sourceVideoCodec:
type: string
example: h264
sourceAudioCodec:
type: string
example: aac
videoDecision:
type: string
example: transcode
audioDecision:
type: string
example: transcode
subtitleDecision:
type: string
example: burn
protocol:
type: string
example: http
container:
type: string
example: mkv
videoCodec:
type: string
example: h264
audioCodec:
type: string
example: opus
audioChannels:
type: integer
format: int32
example: 1
transcodeHwRequested:
type: boolean
example: true
timeStamp:
type: number
example: 1705895805.4919229
maxOffsetAvailable:
type: number
example: 29.53
minOffsetAvailable:
type: number
example: 3.003000020980835
example:
- key: vv3i2q2lax92qlzul1hbd4bx
throttled: false
complete: false
progress: 1.7999999523162842
size: -22
speed: 25.100000381469727
error: false
duration: 1445695
remaining: 53
context: streaming
sourceVideoCodec: h264
sourceAudioCodec: aac
videoDecision: transcode
audioDecision: transcode
subtitleDecision: burn
protocol: http
container: mkv
videoCodec: h264
audioCodec: opus
audioChannels: 1
transcodeHwRequested: true
timeStamp: 1705895805.4919229
maxOffsetAvailable: 29.53
minOffsetAvailable: 3.003000020980835
'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
'/transcode/sessions/{sessionKey}':
delete:
tags:
- Sessions
summary: Stop a Transcode Session
operationId: stopTranscodeSession
description: Stop a Transcode Session
parameters:
- name: sessionKey
description: the Key of the transcode session to stop
in: path
schema:
type: string
example: zz7llzqlx8w9vnrsbnwhbmep
required: true
responses:
'204':
description: The Transcode Session ended
'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
/updater/status:
get:
tags:
- Updater
summary: Querying status of updates
description: Querying status of updates
operationId: getUpdateStatus
responses:
'200':
description: The Server Updates
content:
application/json:
schema:
type: object
properties:
MediaContainer:
type: object
properties:
size:
type: integer
format: int32
example: 1
canInstall:
type: boolean
example: false
checkedAt:
type: integer
format: int32
example: 1705801232
downloadURL:
type: string
example: 'https://plex.tv/downloads/latest/5?channel=8&build=linux-x86_64&distro=redhat&X-Plex-Token=xxxxxxxxxxxxxxxxxxxx'
status:
type: integer
format: int32
example: 0
Release:
type: array
items:
type: object
properties:
key:
type: string
example: 'https://plex.tv/updater/releases/5136'
version:
type: string
example: 1.40.0.7775-456fbaf97
added:
type: string
example: |-
(PLEASE NOTE) This version makes changes to the database which will make it compatible only with server versions 1.31.2 or higher (released March 14). You will not be able to use your database on Plex Media Server versions lower than this after this update. Please also be patient when updating to this version if you have a very large database and allow the upgrade process to finish.
(Collections) Items added to a collection from the item context menu will now lock the collection field on the items (#12793)
(Music) Store track genres and add filtering options (#14653)
(Music) Support ID3v2.4 null-separated tags for genres and release type (#14653)
(View History) No longer create a view history entry for items marked as played (#10888)
(Web) Updated to 4.118.0
fixed:
type: string
example: |-
(Agents) Changing a 'Other Videos' type library to the modern movie agent would fail (#14483)
(Agents) It is possible that agents are not initialised during startup on rare occasions (#14654)
(Agents) Remove the legacy OpenSubtitles agent which is no longer supported upstream (#14667)
(Collection) Server could become unresponsive when collection membership changes (#14612)
(DVR) Previously watched recordings could be deleted without being watched again (#13779)
(Libraries) When performing fix match on items from certain music libraries the language would default to Arabic (#14501)
(Library) The Content Rating not equal to None filter does not work (#14620)
(Search) Album search results could contain all the album's tracks too (#14486)
(Subtitles) In some circumstances, sidecar subtitles can show up for media when they're no longer available (#14674)
(Transcoder) HW encoding would fail on devices with no rate control (#14222)
(Transcoder) Software transcoding on Ubuntu could cause unexpected behavior (#14605)
downloadURL:
type: string
example: 'https://plex.tv/downloads/latest/5?channel=8&build=linux-x86_64&distro=redhat&X-Plex-Token=xxxxxxxxxxxxxxxxxxxx'
state:
type: string
example: notify
example:
- key: 'https://plex.tv/updater/releases/5136'
version: 1.40.0.7775-456fbaf97
added: |-
(PLEASE NOTE) This version makes changes to the database which will make it compatible only with server versions 1.31.2 or higher (released March 14). You will not be able to use your database on Plex Media Server versions lower than this after this update. Please also be patient when updating to this version if you have a very large database and allow the upgrade process to finish.
(Collections) Items added to a collection from the item context menu will now lock the collection field on the items (#12793)
(Music) Store track genres and add filtering options (#14653)
(Music) Support ID3v2.4 null-separated tags for genres and release type (#14653)
(View History) No longer create a view history entry for items marked as played (#10888)
(Web) Updated to 4.118.0
fixed: |-
(Agents) Changing a 'Other Videos' type library to the modern movie agent would fail (#14483)
(Agents) It is possible that agents are not initialised during startup on rare occasions (#14654)
(Agents) Remove the legacy OpenSubtitles agent which is no longer supported upstream (#14667)
(Collection) Server could become unresponsive when collection membership changes (#14612)
(DVR) Previously watched recordings could be deleted without being watched again (#13779)
(Libraries) When performing fix match on items from certain music libraries the language would default to Arabic (#14501)
(Library) The Content Rating not equal to None filter does not work (#14620)
(Search) Album search results could contain all the album's tracks too (#14486)
(Subtitles) In some circumstances, sidecar subtitles can show up for media when they're no longer available (#14674)
(Transcoder) HW encoding would fail on devices with no rate control (#14222)
(Transcoder) Software transcoding on Ubuntu could cause unexpected behavior (#14605)
downloadURL: 'https://plex.tv/downloads/latest/5?channel=8&build=linux-x86_64&distro=redhat&X-Plex-Token=xxxxxxxxxxxxxxxxxxxx'
state: notify
'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
/updater/check:
put:
tags:
- Updater
summary: Checking for updates
description: Checking for updates
operationId: checkForUpdates
parameters:
- name: download
description: Indicate that you want to start download any updates found.
required: false
in: query
schema:
type: integer
enum:
- 0
- 1
example: 1
responses:
'200':
description: 'The update check is started, if download is set to 1 and the system is able to update automatically, the update download will start.'
'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
/updater/apply:
put:
tags:
- Updater
summary: Apply Updates
description: |
Note that these two parameters are effectively mutually exclusive. The `tonight` parameter takes precedence and `skip` will be ignored if `tonight` is also passed
operationId: applyUpdates
parameters:
- name: tonight
description: Indicate that you want the update to run during the next Butler execution. Omitting this or setting it to false indicates that the update should install
required: false
in: query
schema:
type: integer
enum:
- 0
- 1
example: 1
- name: skip
description: Indicate that the latest version should be marked as skipped. The <Release> entry for this version will have the `state` set to `skipped`.
required: false
in: query
schema:
type: integer
enum:
- 0
- 1
example: 1
responses:
'200':
description: If the update process started correctly
'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
'500':
description: If the update process failed to start
'/video/:/transcode/universal/start.mpd':
get:
tags:
- Video
summary: Start Universal Transcode
description: Begin a Universal Transcode Session
operationId: startUniversalTranscode
parameters:
- name: hasMDE
description: Whether the media item has MDE
required: true
in: query
schema:
type: number
example: 1
- name: path
description: The path to the media item to transcode
required: true
in: query
schema:
type: string
example: /library/metadata/23409
- name: mediaIndex
description: The index of the media item to transcode
required: true
in: query
schema:
type: number
example: 0
- name: partIndex
description: The index of the part to transcode
required: true
in: query
schema:
type: number
example: 0
- name: protocol
description: The protocol to use for the transcode session
required: true
in: query
schema:
type: string
example: hls
- name: fastSeek
description: Whether to use fast seek or not
required: false
in: query
schema:
type: number
example: 0
- name: directPlay
description: Whether to use direct play or not
required: false
in: query
schema:
type: number
example: 0
- name: directStream
description: Whether to use direct stream or not
required: false
in: query
schema:
type: number
example: 0
- name: subtitleSize
description: The size of the subtitles
required: false
in: query
schema:
type: number
example: 100
- name: subtites
description: The subtitles
required: false
in: query
schema:
type: string
example: burn
- name: audioBoost
description: The audio boost
required: false
in: query
schema:
type: number
example: 100
- name: location
description: The location of the transcode session
required: false
in: query
schema:
type: string
example: lan
- name: mediaBufferSize
description: The size of the media buffer
required: false
in: query
schema:
type: number
example: 102400
- name: session
description: The session ID
required: false
in: query
schema:
type: string
example: zvcage8b7rkioqcm8f4uns4c
- name: addDebugOverlay
description: Whether to add a debug overlay or not
required: false
in: query
schema:
type: number
example: 0
- name: autoAdjustQuality
description: Whether to auto adjust quality or not
required: false
in: query
schema:
type: number
example: 0
responses:
'200':
description: The transcode session has started
'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: Media
description: |
API Calls interacting with Plex Media Server Media
- 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: Sessions
description: |
API Calls that perform search operations with Plex Media Server Sessions
- name: User
description: |
API Calls that perform operations with Plex Media Server Users
- name: Video
description: |
API Calls that perform operations with Plex Media Server Videos
- name: Plex
description: |
API Calls that perform operations directly against https://Plex.tv
Reference in New Issue View Git Blame Copy Permalink