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 enum: - http - https ip: default: 10.10.10.47 port: default: "32400" x-speakeasy-globals: parameters: - 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 example: Postman required: true 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: type: object properties: id: type: string example: EnableDatabaseTrace label: type: string example: "" summary: type: string example: "" type: type: string example: bool default: type: boolean example: false value: type: boolean example: false hidden: type: boolean example: true advanced: type: boolean example: false group: type: string example: "" enumValues: type: string example: "1:admin only|2:everyone" "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 "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). - ``: 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 Genre: type: array items: type: object properties: tag: type: string example: Animation Country: type: array items: type: object properties: tag: type: string example: United States of America Director: type: array items: type: object properties: tag: type: string example: Nathan Greno Role: type: array items: type: object properties: tag: type: string example: Donna Murphy Writer: type: array items: type: object properties: tag: type: string example: Wilhelm Grimm skipCount: type: integer format: int32 example: 1 chapterSource: type: string example: media promoted: type: boolean example: true random: type: boolean example: 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 "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 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 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 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 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 "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 example: 1 - 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 Genre: type: array items: type: object properties: tag: type: string example: Adventure Country: type: array items: type: object properties: tag: type: string example: United States of America Director: type: array items: type: object properties: tag: type: string example: James Cameron Writer: type: array items: type: object properties: tag: type: string example: James Cameron Role: type: array items: type: object properties: tag: type: string example: 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 "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}/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 "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}": 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 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 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 Guid: x-speakeasy-name-override: guids type: array items: type: object properties: id: type: string example: "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 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" 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" 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" 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" "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 "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 example: Postman 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 example: Postman 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 "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 "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 "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 Genre: type: array items: type: object properties: tag: type: string example: Action Country: type: array items: type: object properties: tag: type: string example: United States of America Director: type: array items: type: object properties: tag: type: string example: Joss Whedon Writer: type: array items: type: object properties: tag: type: string example: Joss Whedon Role: type: array items: type: object properties: tag: type: string example: Gina Torres "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 "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: - Authentication 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: - Authentication 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 schema: type: integer 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 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" 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 "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 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 "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 "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 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: 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 - name: Statistics description: | API Calls that perform operations with Plex Media Server Statistics