> ## Documentation Index
> Fetch the complete documentation index at: https://personal-92-migrate-dev-docs-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Shuffle a play queue
> Shuffle a play queue (or reshuffles if already shuffled). The currently selected item is maintained. Note that this is currently only supported for play queues *without* an Up Next area. Returns the modified play queue.
## OpenAPI
````yaml /openapi-with-code-samples.yaml put /playQueues/{playQueueId}/shuffle
openapi: 3.1.1
info:
title: Plex Media Server
version: 1.1.1
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{IP-description}.{identifier}.plex.direct:{port}
variables:
identifier:
description: The unique identifier of this particular PMS
default: 0123456789abcdef0123456789abcdef
IP-description:
description: A `-` separated string of the IPv4 or IPv6 address components
default: 1-2-3-4
port:
default: '32400'
- url: '{protocol}://{host}:{port}'
variables:
protocol:
description: The network protocol to use. Typically (`http` or `https`)
default: http
host:
description: >
The Host of the PMS.
If using on a local network, this is the internal IP address of the
server hosting the PMS.
If using on an external network, this is the external IP address for
your network, and requires port forwarding.
If using a reverse proxy, this would be the external DNS domain for
your network, and requires the proxy handle port forwarding.
default: localhost
port:
description: >
The Port number configured on the PMS. Typically (`32400`).
If using a reverse proxy, this would be the port number configured on
the proxy.
default: '32400'
- url: '{full_server_url}'
variables:
full_server_url:
description: The full manual URL to access the PMS
default: http://localhost:32400
security:
- token:
- shared user
- admin
tags:
- name: Activities
description: >
Activities 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.
- name: Butler
description: >-
The butler is responsible for running periodic tasks. Some tasks run
daily, others every few days, and some weekly. These includes database
maintenance, metadata updating, thumbnail generation, media analysis, and
other tasks.
- name: Collections
description: API Operations against the Collections
- name: Content
description: The actual content of the media provider
- name: Devices
description: >
Media grabbers provide ways for media to be obtained for a given protocol.
The simplest ones are `stream` and `download`. More complex grabbers can
have associated devices
Network tuners can present themselves on the network using the Simple
Service Discovery Protocol and Plex Media Server will discover them. The
following XML is an example of the data returned from SSDP. The
`deviceType`, `serviceType`, and `serviceId` values must remain as they
are in the example in order for PMS to properly discover the device. Other
less-obvious fields are described in the parameters section below.
Example SSDP output
```
1
0
urn:plex-tv:device:Media:1
Turing Hopper 3000
Plex, Inc.
https://plex.tv/
Turing Hopper 3000 Media Grabber
Plex Media Grabber
1
https://plex.tv
uuid:42fde8e4-93b6-41e5-8a63-12d848655811
http://10.0.0.5:8088
urn:plex-tv:service:MediaGrabber:1
urn:plex-tv:serviceId:MediaGrabber
```
- UDN: (string) A UUID for the device. This should be unique across models of a device at minimum.
- URLBase: (string) The base HTTP URL for the device from which all of the other endpoints are hosted.
- name: Download Queue
description: API Operations against the Download Queue
- name: DVRs
description: >
The DVR provides means to watch and record live TV. This section of
endpoints describes how to setup the DVR itself
- name: EPG
description: >
The EPG (Electronic Program Guide) is responsible for obtaining metadata
for what is airing on each channel and when
- name: Events
description: >
The server can notify clients in real-time of a wide range of events, from
library scanning, to preferences being modified, to changes to media, and
many other things. This is also the mechanism by which activity progress
is reported.
Two protocols for receiving the events are available: EventSource (also
known as SSE), and WebSocket.
- name: General
description: >-
General endpoints for basic PMS operation not specific to any media
provider
- name: Hubs
description: The hubs within a media provider
- name: Library
description: >-
Library endpoints which are outside of the Media Provider API. Typically
this is manipulation of the library (adding/removing sections, modifying
preferences, etc).
- name: Library Collections
description: >-
Endpoints for manipulating collections. In addition to these endpoints,
`/library/collections/:collectionId/X` will be rerouted to
`/library/metadata/:collectionId/X` and respond to those endpoints as
well.
x-displayName: 'Library: Collections'
- name: Library Playlists
description: Endpoints for manipulating playlists.
x-displayName: 'Library: Playlists'
- name: Live TV
description: |
LiveTV contains the playback sessions of a channel from a DVR device
- name: Log
description: Logging mechanism to allow clients to log to the server
- name: Play Queue
description: >-
The playqueue feature within a media provider
A play queue represents the current list of media for playback. Although
queues are persisted by the server, they should be regarded by the user as
a fairly lightweight, an ephemeral list of items queued up for playback in
a session. There is generally one active queue for each type of media
(music, video, photos) that can be added to or destroyed and replaced with
a fresh queue.
Play Queues has a region, which we refer to in this doc (partially for
historical reasons) as "Up Next". This region is defined by
`playQueueLastAddedItemID` existing on the media container. This follows
iTunes' terminology. It is a special region after the currently playing
item but before the originally-played items. This enables "Party Mode"
listening/viewing, where items can be added on-the-fly, and normal queue
playback resumed when completed.
You can visualize the play queue as a sliding window in the complete list
of media queued for playback. This model is important when scaling to
larger play queues (e.g. shuffling 40,000 audio tracks). The client only
needs visibility into small areas of the queue at any given time, and the
server can optimize access in this fashion.
All created play queues will have an empty "Up Next" area - unless the
item is an album and no `key` is provided. In this case the "Up Next" area
will be populated by the contents of the album. This is to allow queueing
of multiple albums - since the 'Add to Up Next' will insert after all the
tracks. This means that If you're creating a PQ from an album, you can
only shuffle it if you set `key`. This is due to the above implicit
queueing of albums when no `key` is provided as well as the current
limitation that you cannot shuffle a PQ with an "Up Next" area.
The play queue window advances as the server receives timeline requests.
The client needs to retrieve the play queue as the “now playing” item
changes. There is no play queue API to update the playing item.
- name: Playlist
description: Media playlists that can be created and played back
- name: Preferences
description: API Operations against the Preferences
- name: Provider
description: >-
Media providers are the starting points for the entire Plex Media Server
media library API. It defines the paths for the groups of endpoints. The
`/media/providers` should be the only hard-coded path in clients when
accessing the media library. Non-media library endpoints are outside the
scope of the media provider. See the description in See [the section in
API Info](#section/API-Info/Media-Providers) for more information on how
to use media providers.
- name: Rate
description: Operations for rating media items (thumbs up/down, star ratings, etc.)
- name: Search
description: The search feature within a media provider
- name: Status
description: >-
The status endpoints give you information about current playbacks, play
history, and even terminating sessions.
- name: Subscriptions
description: >
Subscriptions determine which media will be recorded and the criteria for
selecting an airing when multiple are available
- name: Timeline
description: The actions feature within a media provider
- name: Transcoder
description: API Operations against the Transcoder
- name: UltraBlur
description: Service provided to compute UltraBlur colors and images.
- 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.
paths:
/playQueues/{playQueueId}/shuffle:
put:
tags:
- Play Queue
summary: Shuffle a play queue
description: >-
Shuffle a play queue (or reshuffles if already shuffled). The currently
selected item is maintained. Note that this is currently only supported
for play queues *without* an Up Next area. Returns the modified play
queue.
operationId: shuffle
parameters:
- $ref: '#/components/parameters/accepts'
- $ref: '#/components/parameters/X-Plex-Client-Identifier'
- $ref: '#/components/parameters/X-Plex-Product'
- $ref: '#/components/parameters/X-Plex-Version'
- $ref: '#/components/parameters/X-Plex-Platform'
- $ref: '#/components/parameters/X-Plex-Platform-Version'
- $ref: '#/components/parameters/X-Plex-Device'
- $ref: '#/components/parameters/X-Plex-Model'
- $ref: '#/components/parameters/X-Plex-Device-Vendor'
- $ref: '#/components/parameters/X-Plex-Device-Name'
- $ref: '#/components/parameters/X-Plex-Marketplace'
- name: playQueueId
description: The ID of the play queue.
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MediaContainerWithPlaylistMetadata'
'400':
$ref: '#/components/responses/400'
'404':
description: Play queue not found or current item not found
content:
text/html: {}
x-codeSamples:
- lang: go
label: PlexGO
source: "package main\n\nimport(\n\t\"context\"\n\t\"github.com/LukeHagar/plexgo/models/components\"\n\t\"github.com/LukeHagar/plexgo\"\n\t\"github.com/LukeHagar/plexgo/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := plexgo.New(\n plexgo.WithAccepts(components.AcceptsApplicationXML),\n plexgo.WithClientIdentifier(\"abc123\"),\n plexgo.WithProduct(\"Plex for Roku\"),\n plexgo.WithVersion(\"2.4.1\"),\n plexgo.WithPlatform(\"Roku\"),\n plexgo.WithPlatformVersion(\"4.3 build 1057\"),\n plexgo.WithDevice(\"Roku 3\"),\n plexgo.WithModel(\"4200X\"),\n plexgo.WithDeviceVendor(\"Roku\"),\n plexgo.WithDeviceName(\"Living Room TV\"),\n plexgo.WithMarketplace(\"googlePlay\"),\n plexgo.WithSecurity(\"\"),\n )\n\n res, err := s.PlayQueue.Shuffle(ctx, operations.ShuffleRequest{\n PlayQueueID: 316150,\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.MediaContainerWithPlaylistMetadata != nil {\n // handle response\n }\n}"
- lang: java
label: PlexJava
source: |-
package hello.world;
import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.operations.ShuffleRequest;
import dev.plexapi.sdk.models.operations.ShuffleResponse;
import dev.plexapi.sdk.models.shared.Accepts;
import java.lang.Exception;
public class Application {
public static void main(String[] args) throws Exception {
PlexAPI sdk = PlexAPI.builder()
.accepts(Accepts.APPLICATION_XML)
.clientIdentifier("abc123")
.product("Plex for Roku")
.version("2.4.1")
.platform("Roku")
.platformVersion("4.3 build 1057")
.device("Roku 3")
.model("4200X")
.deviceVendor("Roku")
.deviceName("Living Room TV")
.marketplace("googlePlay")
.token(System.getenv().getOrDefault("TOKEN", ""))
.build();
ShuffleRequest req = ShuffleRequest.builder()
.playQueueId(316150L)
.build();
ShuffleResponse res = sdk.playQueue().shuffle()
.request(req)
.call();
if (res.mediaContainerWithPlaylistMetadata().isPresent()) {
// handle response
}
}
}
- lang: typescript
label: PlexJS
source: |-
import { PlexAPI } from "@lukehagar/plexjs";
import { Accepts } from "@lukehagar/plexjs/models/shared";
const plexAPI = new PlexAPI({
accepts: Accepts.ApplicationXml,
clientIdentifier: "abc123",
product: "Plex for Roku",
version: "2.4.1",
platform: "Roku",
platformVersion: "4.3 build 1057",
device: "Roku 3",
model: "4200X",
deviceVendor: "Roku",
deviceName: "Living Room TV",
marketplace: "googlePlay",
token: "",
});
async function run() {
const result = await plexAPI.playQueue.shuffle({
playQueueId: 316150,
});
console.log(result);
}
run();
components:
parameters:
accepts:
name: accepts
description: Indicates the client accepts the indicated media types
in: header
schema:
type: string
default: application/xml
enum:
- application/json
- application/xml
X-Plex-Client-Identifier:
name: X-Plex-Client-Identifier
x-speakeasy-name-override: Client-Identifier
in: header
description: An opaque identifier unique to the client
required: true
schema:
type: string
example: abc123
example: abc123
X-Plex-Product:
name: X-Plex-Product
x-speakeasy-name-override: Product
in: header
description: The name of the client product
schema:
type: string
example: Plex for Roku
example: Plex for Roku
X-Plex-Version:
name: X-Plex-Version
x-speakeasy-name-override: Version
in: header
description: The version of the client application
schema:
type: string
example: 2.4.1
example: 2.4.1
X-Plex-Platform:
name: X-Plex-Platform
x-speakeasy-name-override: Platform
in: header
description: The platform of the client
schema:
type: string
example: Roku
example: Roku
X-Plex-Platform-Version:
name: X-Plex-Platform-Version
x-speakeasy-name-override: Platform-Version
in: header
description: The version of the platform
schema:
type: string
example: 4.3 build 1057
example: 4.3 build 1057
X-Plex-Device:
name: X-Plex-Device
x-speakeasy-name-override: Device
in: header
description: A relatively friendly name for the client device
schema:
type: string
example: Roku 3
example: Roku 3
X-Plex-Model:
name: X-Plex-Model
x-speakeasy-name-override: Model
in: header
description: A potentially less friendly identifier for the device model
schema:
type: string
example: 4200X
example: 4200X
X-Plex-Device-Vendor:
name: X-Plex-Device-Vendor
x-speakeasy-name-override: Device-Vendor
in: header
description: The device vendor
schema:
type: string
example: Roku
example: Roku
X-Plex-Device-Name:
name: X-Plex-Device-Name
x-speakeasy-name-override: Device-Name
in: header
description: A friendly name for the client
schema:
type: string
example: Living Room TV
example: Living Room TV
X-Plex-Marketplace:
name: X-Plex-Marketplace
x-speakeasy-name-override: Marketplace
in: header
description: The marketplace on which the client application is distributed
schema:
type: string
example: googlePlay
example: googlePlay
schemas:
MediaContainerWithPlaylistMetadata:
type: object
properties:
MediaContainer:
allOf:
- $ref: '#/components/schemas/MediaContainer'
- type: object
properties:
Metadata:
type: array
items:
allOf:
- type: object
properties:
readOnly:
description: >-
If we return this as true then this playlist
cannot be altered or deleted directly by the
client.
type: boolean
composite:
description: A composite image for the playlist.
type: string
duration:
description: The total duration of the playlist in ms
type: integer
key:
description: Leads to a list of items in the playlist.
type: string
leafCount:
description: The number of items in the playlist.
type: integer
playlistType:
description: The type of the playlist.
type: string
enum:
- audio
- video
- photo
smart:
description: Whether or not the playlist is smart.
type: boolean
specialPlaylistType:
description: >-
If this is a special playlist, this returns its
type (e.g. favorites).
type: string
- $ref: '#/components/schemas/Metadata'
MediaContainer:
description: >
`MediaContainer` is the root element of most Plex API responses. It
serves as a generic container for various types of content (Metadata,
Hubs, Directories, etc.) and includes pagination information (offset,
size, totalSize) when applicable.
Common attributes: - identifier: Unique identifier for this container -
size: Number of items in this response page - totalSize: Total number of
items available (for pagination) - offset: Starting index of this page
(for pagination)
The container often "hoists" common attributes from its children. For
example, if all tracks in a container share the same album title, the
`parentTitle` attribute may appear on the MediaContainer rather than
being repeated on each track.
type: object
properties:
identifier:
type: string
offset:
description: >
The offset of where this container page starts among the total
objects available. Also provided in the `X-Plex-Container-Start`
header.
type: integer
size:
type: integer
totalSize:
description: >
The total size of objects available. Also provided in the
`X-Plex-Container-Total-Size` header.
type: integer
Metadata:
description: >
Items in a library are referred to as "metadata items." These metadata
items are distinct from "media items" which represent actual instances
of media that can be consumed. Consider a TV library that has a single
video file in it for a particular episode of a show. The library has a
single media item, but it has three metadata items: one for the show,
one for the season, and one for the episode. Consider a movie library
that has two video files in it: the same movie, but two different
resolutions. The library has a single metadata item for the movie, but
that metadata item has two media items, one for each resolution.
Additionally a "media item" will have one or more "media parts" where
the the parts are intended to be watched together, such as a CD1 and CD2
parts of the same movie.
Note that when a metadata item has multiple media items, those media
items should be isomorphic. That is, a 4K version and 1080p version of a
movie are different versions of the same movie. They have the same
duration, same summary, same rating, etc. and they can generally be
considered interchangeable. A theatrical release vs. director's cut vs.
unrated version on the other hand would be separate metadata items.
Metadata items can often live in a hierarchy with relationships between
them. For example, the metadata item for an episodes is associated with
a season metadata item which is associated with a show metadata item. A
similar hierarchy exists with track, album, and artist and photos and
photo album. The relationships may be expressed via relative terms and
absolute terms. For example, "leaves" refer to metadata items which has
associated media (there is no media for a season nor show). A show will
have "children" in the form of seasons and a season will have "children"
in the form of episodes and episodes have "parent" in the form of a
season which has a "parent" in the form of a show. Similarly, a show
has "grandchildren" in the form of episodse and an episode has a
"grandparent" in the form of a show.
type: object
additionalProperties: true
required:
- addedAt
- key
- title
- type
properties:
title:
description: The title of the item (e.g. “300” or “The Simpsons”)
type: string
type:
description: The type of the video item, such as `movie`, `episode`, or `clip`.
type: string
absoluteIndex:
description: >-
When present, contains the disc number for a track on multi-disc
albums.
type: integer
format: int32
addedAt:
description: >-
In units of seconds since the epoch, returns the time at which the
item was added to the library.
type: integer
format: int64
art:
description: When present, the URL for the background artwork for the item.
type: string
example: /library/metadata/58683/art/1703239236
audienceRating:
description: Some rating systems separate reviewer ratings from audience ratings
type: number
format: float
minimum: 0
maximum: 10
audienceRatingImage:
description: >-
A URI representing the image to be shown with the audience rating
(e.g. rottentomatoes://image.rating.spilled).
type: string
Autotag:
type: array
items:
$ref: '#/components/schemas/Tag'
banner:
description: When present, the URL for a banner graphic for the item.
type: string
chapterSource:
description: >-
When present, indicates the source for the chapters in the media
file. Can be media (the chapters were embedded in the media itself),
agent (a metadata agent computed them), or mixed (a combination of
the two).
type: string
example: media
childCount:
type: integer
format: int32
description: The number of child items associated with this media item.
example: 1
composite:
description: >-
When present, the URL for a composite image for descendent items
(e.g. photo albums or playlists).
type: string
contentRating:
description: If known, the content rating (e.g. MPAA) for an item.
type: string
Country:
type: array
items:
$ref: '#/components/schemas/Tag'
Director:
type: array
items:
$ref: '#/components/schemas/Tag'
duration:
description: When present, the duration for the item, in units of milliseconds.
type: integer
format: int32
Filter:
description: Typically only seen in metadata at a library's top level
type: array
items:
$ref: '#/components/schemas/Filter'
Genre:
type: array
items:
$ref: '#/components/schemas/Tag'
grandparentArt:
description: The `art` of the grandparent
type: string
grandparentGuid:
type: string
description: The GUID of the grandparent media item.
example: plex://show/5d9c081b170e24001f2a7be4
grandparentHero:
description: The `hero` of the grandparent
type: string
grandparentKey:
description: The `key` of the grandparent
type: string
grandparentRatingKey:
description: The `ratingKey` of the grandparent
type: string
grandparentTheme:
description: The `theme` of the grandparent
type: string
grandparentThumb:
description: The `thumb` of the grandparent
type: string
grandparentTitle:
description: The `title` of the grandparent
type: string
guid:
type: string
description: The globally unique identifier for the media item.
example: plex://movie/5d7768ba96b655001fdc0408
Guid:
x-speakeasy-name-override: guids
type: array
items:
type: object
required:
- id
properties:
id:
type: string
description: >
The unique identifier for the Guid. Can be prefixed with
imdb://, tmdb://, tvdb://
pattern: ^(imdb|tmdb|tvdb)://.+$
example:
imdbExample:
summary: IMDB example
value: imdb://tt13015952
tmdbExample:
summary: TMDB example
value: tmdb://2434012
tvdbExample:
summary: TVDB example
value: tvdb://7945991
hero:
description: When present, the URL for a hero image for the item.
type: string
Image:
type: array
items:
$ref: '#/components/schemas/Image'
index:
description: >-
When present, this represents the episode number for episodes,
season number for seasons, or track number for audio tracks.
type: integer
format: int32
key:
description: >-
The key at which the item's details can be fetched. In many cases a
metadata item may be passed without all the details (such as in a
hub) and this key corresponds to the endpoint to fetch additional
details.
type: string
lastViewedAt:
allOf:
- $ref: '#/components/schemas/PlexDateTime'
- description: >-
When a user has watched or listened to an item, this contains a
timestamp (epoch seconds) for that last consumption time.
leafCount:
description: For shows and seasons, contains the number of total episodes.
type: integer
format: int32
Media:
type: array
items:
$ref: '#/components/schemas/Media'
originallyAvailableAt:
description: >-
When present, in the format YYYY-MM-DD [HH:MM:SS] (the
hours/minutes/seconds part is not always present). The air date, or
a higher resolution release date for an item, depending on type. For
example, episodes usually have air date like 1979-08-10 (we don't
use epoch seconds because media existed prior to 1970). In some
cases, recorded over-the-air content has higher resolution air date
which includes a time component. Albums and movies may have
day-resolution release dates as well.
type: string
format: date
example: '2022-12-14'
originalTitle:
description: >-
When present, used to indicate an item's original title, e.g. a
movie's foreign title.
type: string
parentGuid:
type: string
description: The GUID of the parent media item.
example: plex://show/5d9c081b170e24001f2a7be4
parentHero:
description: The `hero` of the parent
type: string
parentIndex:
description: The `index` of the parent
type: integer
format: int32
parentKey:
description: The `key` of the parent
type: string
parentRatingKey:
description: The `ratingKey` of the parent
type: string
parentThumb:
description: The `thumb` of the parent
type: string
parentTitle:
description: The `title` of the parent
type: string
primaryExtraKey:
description: >-
Indicates that the item has a primary extra; for a movie, this is a
trailer, and for a music track it is a music video. The URL points
to the metadata details endpoint for the item.
type: string
prompt:
description: Prompt to give the user for this directory (such as `Search Movies`)
type: string
rating:
description: >-
When present, the rating for the item. The exact meaning and
representation depends on where the rating was sourced from.
type: number
format: float
minimum: 0
maximum: 10
Rating:
type: array
items:
$ref: '#/components/schemas/Tag'
x-speakeasy-name-override: RatingArray
ratingCount:
description: Number of ratings under this metadata
type: integer
format: int32
ratingImage:
description: >-
When present, indicates an image to be shown with the rating. This
is passed back as a small set of defined URI values, e.g.
rottentomatoes://image.rating.rotten.
type: string
ratingKey:
description: >-
This is the opaque string to be passed into timeline, scrobble, and
rating endpoints to identify them. While it often appears to be
numeric, this is not guaranteed.
type: string
Role:
type: array
items:
$ref: '#/components/schemas/Tag'
search:
description: Indicates this is a search directory
type: boolean
secondary:
description: >-
Used by old clients to provide nested menus allowing for primative
(but structured) navigation.
type: boolean
skipChildren:
description: >-
When found on a show item, indicates that the children (seasons)
should be skipped in favor of the grandchildren (episodes). Useful
for mini-series, etc.
oneOf:
- type: boolean
- type: string
enum:
- '0'
- '1'
skipParent:
description: >-
When present on an episode or track item, indicates parent should be
skipped in favor of grandparent (show).
oneOf:
- type: boolean
- type: string
enum:
- '0'
- '1'
Sort:
description: Typically only seen in metadata at a library's top level
type: array
items:
$ref: '#/components/schemas/Sort'
studio:
description: >-
When present, the studio or label which produced an item (e.g. movie
studio for movies, record label for albums).
type: string
subtype:
description: >-
The subtype of the video item, such as `photo` when the video item
is in a photo library
type: string
summary:
description: >-
When present, the extended textual information about the item (e.g.
movie plot, artist biography, album review).
type: string
tagline:
description: >-
When present, a pithy one-liner about the item (usually only seen
for movies).
type: string
theme:
description: >-
When present, the URL for theme music for the item (usually only for
TV shows).
type: string
example: /library/metadata/1/theme/1705636920
thumb:
description: >-
When present, the URL for the poster or thumbnail for the item. When
available for types like movie, it will be the poster graphic, but
fall-back to the extracted media thumbnail.
type: string
example: /library/metadata/58683/thumb/1703239236
titleSort:
description: >-
Whene present, this is the string used for sorting the item. It's
usually the title with any leading articles removed (e.g.
“Simpsons”).
type: string
updatedAt:
description: >-
In units of seconds since the epoch, returns the time at which the
item was last changed (e.g. had its metadata updated).
type: integer
userRating:
description: When the user has rated an item, this contains the user rating
type: number
format: float
minimum: 0
maximum: 10
viewCount:
description: >-
When a users has completed watched or listened to an item, this
attribute contains the number of consumptions.
type: integer
format: int32
viewedLeafCount:
description: For shows and seasons, contains the number of viewed episodes.
type: integer
format: int32
viewOffset:
description: >-
When a user is in the process of viewing or listening to this item,
this attribute contains the current offset, in units of
milliseconds.
type: integer
format: int32
Writer:
type: array
items:
$ref: '#/components/schemas/Tag'
year:
description: >-
When present, the year associated with the item's release (e.g.
release year for a movie).
type: integer
format: int32
Tag:
description: >
A variety of extra information about a metadata item is included as
tags. These tags use their own element names such as `Genre`, `Writer`,
`Directory`, and `Role`. Individual tag types may introduce their own
extra attributes.
type: object
required:
- tag
properties:
confidence:
description: Measure of the confidence of an automatic tag
type: number
context:
type: string
filter:
description: >-
A filter parameter that can be used to query for more content that
matches this tag value.
type: string
example: actor=49
id:
type: integer
format: int32
ratingKey:
description: >-
The rating key (Media ID) of this media item. Note: Although this is
always an integer, it is represented as a string in the API.
type: string
example: '58683'
role:
description: The role this actor played
type: string
example: Secretary
tag:
description: The value of the tag (the name)
type: string
example: Shaun Lawton
tagKey:
description: >-
Plex identifier for this tag which can be used to fetch additional
information from plex.tv
type: string
example: 5d3ee12c4cde6a001c3e0b27
tagType:
type: integer
format: int32
thumb:
type: string
example: http://image.tmdb.org/t/p/original/lcJ8qM51ClAR2UzXU1mkZGfnn3o.jpg
Filter:
allOf:
- $ref: '#/components/schemas/Directory'
- description: >
Each `Filter` object contains a description of the filter. Note that
it is not an exhaustive list of the full media query language, but
an important subset useful for top-level API.
type: object
properties:
title:
description: The title for the filter.
type: string
filter:
description: >-
This represents the filter name used for the filter, which can
be used to construct complex media queries with.
type: string
filterType:
description: >-
This is either `string`, `integer`, or `boolean`, and describes
the type of values used for the filter.
type: string
key:
description: >-
This provides the endpoint where the possible range of values
for the filter can be retrieved (e.g. for a "Genre" filter, it
returns a list of all the genres in the library). This will
include a `type` argument that matches the metadata type of the
Type element.
type: string
Image:
description: >
Images such as movie posters and background artwork are represented by
Image elements.
type: object
properties:
type:
description: Describes both the purpose and intended presentation of the image.
type: string
enum:
- background
- backgroundSquare
- banner
- clearLogo
- coverPoster
- snapshot
alt:
description: Title to use for accessibility.
type: string
url:
description: The relative path or absolute url for the image.
type: string
PlexDateTime:
type:
- integer
example: 1556281940
description: Unix epoch datetime in seconds
format: int64
Media:
description: >
`Media` represents an one or more media files (parts) and is a child of
a metadata item. There aren't necessarily any guaranteed attributes on
media elements since the attributes will vary based on the type. The
possible attributes are not documented here, but they typically have
self-evident names. High-level media information that can be used for
badging and flagging, such as `videoResolution` and codecs, is included
on the media element.
type: object
additionalProperties: true
required:
- id
properties:
aspectRatio:
type: number
format: float
example: 2.35
audioChannels:
type: integer
format: int32
example: 2
audioCodec:
type: string
example: aac
audioProfile:
type: string
example: lc
bitrate:
type: integer
format: int32
example: 5612
container:
type: string
example: mov
duration:
type: integer
format: int32
example: 150192
has64bitOffsets:
type: boolean
example: false
hasVoiceActivity:
oneOf:
- type: boolean
- type: string
enum:
- '0'
- '1'
example: '0'
description: >
Voice activity detection availability flag returned by PMS.
PMS may return this as a boolean or as string values (`"0"` or
`"1"`).
height:
type: integer
format: int32
example: 544
id:
type: integer
format: int64
example: 1
optimizedForStreaming:
type: integer
format: int32
enum:
- 0
- 1
Part:
type: array
items:
$ref: '#/components/schemas/Part'
videoCodec:
type: string
example: h264
videoFrameRate:
type: string
example: 24p
videoProfile:
type: string
example: main
videoResolution:
type: string
example: '720'
width:
type: integer
format: int32
example: 1280
Sort:
allOf:
- $ref: '#/components/schemas/Directory'
- description: |
Each `Sort` object contains a description of the sort field.
type: object
properties:
title:
description: The title of the field.
type: string
default:
description: If present, this sort is the default and in this direction
type: string
enum:
- asc
- desc
defaultDirection:
description: This default diction of this sort
type: string
enum:
- asc
- desc
descKey:
description: The key for sorting this field in reverse order
type: string
firstCharacterKey:
description: >-
The key to use to get items sorted by this field and indexed by
the first character
type: string
key:
description: The key to use in the sort field to make items sort by this item
type: string
Directory:
type: object
additionalProperties: true
properties:
title:
type: string
type:
type: string
art:
type: string
content:
type: boolean
filter:
type: string
hasPrefs:
type: boolean
hasStoreServices:
type: boolean
hubKey:
type: string
identifier:
type: string
key:
type: string
lastAccessedAt:
type: integer
Pivot:
type: array
items:
type: object
properties:
title:
type: string
type:
type: string
context:
type: string
id:
type: string
key:
type: string
symbol:
type: string
share:
type: integer
thumb:
type: string
titleBar:
type: string
Part:
description: >
`Part` represents a particular file or "part" of a media item. The part
is the playable unit of the media hierarchy. Suppose that a movie
library contains a movie that is broken up into files, reminiscent of a
movie split across two BDs. The metadata item represents information
about the movie, the media item represents this instance of the movie at
this resolution and quality, and the part items represent the two
playable files. If another media were added which contained the joining
of these two parts transcoded down to a lower resolution, then this
metadata would contain 2 medias, one with 2 parts and one with 1 part.
type: object
additionalProperties: true
required:
- id
- key
properties:
accessible:
type: boolean
description: Indicates if the part is accessible.
example: true
audioProfile:
type: string
example: lc
container:
description: The container of the media file, such as `mp4` or `mkv`
type: string
example: mov
duration:
description: The duration of the media item, in milliseconds
type: integer
format: int32
example: 150192
exists:
type: boolean
description: Indicates if the part exists.
example: true
file:
description: The local file path at which the part is stored on the server
type: string
example: /home/schuyler/Videos/Trailers/Cloud Atlas (2012).mov
has64bitOffsets:
type: boolean
example: false
id:
type: integer
format: int64
example: 1
indexes:
type: string
example: sd
key:
description: The key from which the media can be streamed
type: string
example: /library/parts/1/1531779263/file.mov
optimizedForStreaming:
type: boolean
example: false
size:
description: The size of the media, in bytes
type: integer
format: int64
example: 105355654
Stream:
type: array
items:
$ref: '#/components/schemas/Stream'
videoProfile:
type: string
example: main
Stream:
description: >
`Stream` represents a particular stream from a media item, such as the
video stream, audio stream, or subtitle stream. The stream may either be
part of the file represented by the parent `Part` or, especially for
subtitles, an external file. The stream contains more detailed
information about the specific stream. For example, a video may include
the `aspectRatio` at the `Media` level, but detailed information about
the video stream like the color space will be included on the `Stream`
for the video stream. Note that photos do not have streams (mostly as
an optimization).
type: object
additionalProperties: true
required:
- id
- key
- codec
- displayTitle
- streamType
properties:
default:
type: boolean
description: Indicates if this stream is default.
example: true
audioChannelLayout:
type: string
description: Audio channel layout.
example: 5.1(side)
channels:
type: integer
format: int32
description: Number of audio channels (for audio streams).
example: 6
bitDepth:
type: integer
format: int32
description: Bit depth of the video stream.
example: 10
DOVIBLCompatID:
type: integer
format: int32
description: Dolby Vision BL compatibility ID.
example: 1
DOVIBLPresent:
type: boolean
description: Indicates if Dolby Vision BL is present.
example: true
DOVIELPresent:
type: boolean
description: Indicates if Dolby Vision EL is present.
example: false
DOVILevel:
type: integer
format: int32
description: Dolby Vision level.
example: 6
DOVIPresent:
type: boolean
description: Indicates if Dolby Vision is present.
example: true
DOVIProfile:
type: integer
format: int32
description: Dolby Vision profile.
example: 8
DOVIRPUPresent:
type: boolean
description: Indicates if Dolby Vision RPU is present.
example: true
DOVIVersion:
type: string
description: Dolby Vision version.
example: '1.0'
bitrate:
type: integer
format: int32
description: Bitrate of the stream.
example: 24743
canAutoSync:
description: Indicates if the stream can auto-sync.
example: false
oneOf:
- type: boolean
- type: string
enum:
- '0'
- '1'
chromaLocation:
type: string
description: Chroma sample location.
example: topleft
chromaSubsampling:
type: string
description: Chroma subsampling format.
example: '4:2:0'
codedHeight:
type: integer
format: int32
description: Coded video height.
example: 1608
codedWidth:
type: integer
format: int32
description: Coded video width.
example: 3840
closedCaptions:
type: boolean
example: true
codec:
description: Codec used by the stream.
type: string
example: hevc
colorPrimaries:
type: string
description: Color primaries used.
example: bt2020
colorRange:
type: string
description: Color range (e.g., tv).
example: tv
colorSpace:
type: string
description: Color space.
example: bt2020nc
colorTrc:
type: string
description: Color transfer characteristics.
example: smpte2084
displayTitle:
description: Display title for the stream.
type: string
example: 4K DoVi/HDR10 (HEVC Main 10)
extendedDisplayTitle:
type: string
description: Extended display title for the stream.
example: 4K DoVi/HDR10 (HEVC Main 10)
frameRate:
type: number
format: float
description: Frame rate of the stream.
example: 23.976
hasScalingMatrix:
type: boolean
example: false
height:
type: integer
format: int32
description: Height of the video stream.
example: 1602
id:
type: integer
format: int32
description: Unique stream identifier.
example: 1002625
index:
description: Index of the stream.
type: integer
format: int32
example: 0
key:
description: Key to access this stream part.
type: string
example: /library/streams/216389
language:
type: string
description: Language of the stream.
example: English
languageCode:
description: ISO language code.
type: string
example: eng
languageTag:
type: string
description: Language tag (e.g., en).
example: en
format:
type: string
description: Format of the stream (e.g., srt).
example: srt
headerCompression:
type: boolean
description: Indicates whether header compression is enabled.
example: true
level:
type: integer
format: int32
description: Video level.
example: 150
original:
type: boolean
description: Indicates if this is the original stream.
example: true
profile:
type: string
description: Video profile.
example: main 10
refFrames:
type: integer
format: int32
description: Number of reference frames.
example: 1
samplingRate:
type: integer
format: int32
description: Sampling rate for the audio stream.
example: 48000
scanType:
type: string
example: progressive
embeddedInVideo:
type: string
example: progressive
selected:
type: boolean
description: Indicates if this stream is selected (applicable for audio streams).
example: true
forced:
type: boolean
example: true
hearingImpaired:
type: boolean
description: Indicates if the stream is for the hearing impaired.
example: true
dub:
type: boolean
description: Indicates if the stream is a dub.
example: true
title:
type: string
description: Optional title for the stream (e.g., language variant).
example: SDH
streamIdentifier:
type: integer
format: int32
example: 1
streamType:
allOf:
- type: integer
format: int32
enum:
- 1
- 2
- 3
example: 1
x-speakeasy-enums:
- VIDEO
- AUDIO
- SUBTITLE
- description: |
Stream type:
- VIDEO = 1 (Video stream)
- AUDIO = 2 (Audio stream)
- SUBTITLE = 3 (Subtitle stream)
width:
type: integer
format: int32
description: Width of the video stream.
example: 3840
responses:
'400':
description: Bad Request
content:
text/html: {}
securitySchemes:
token:
name: X-Plex-Token
description: >
The token which identifies the user accessing the PMS. This can be
either:
- A traditional access token obtained from plex.tv
- A JWT token obtained through the JWT authentication flow
JWT tokens provide better security with:
- Short-lived tokens (7 days expiration)
- Public-key cryptography (ED25519)
- Better clock synchronization
- Individual device revocation capability
type: apiKey
in: header
````