openapi: 3.1.0 info: version: 0.0.3 title: Plex-API description: An Open API Spec for interacting with Plex.tv and Plex Media Server contact: name: Luke Hagar url: 'https://www.LukeHagar.com' email: Lukeslakemail@gmail.com license: url: 'https://opensource.org/license/mit' name: MIT servers: - url: '{protocol}://{ip}:{port}' description: The full address of your Plex Server variables: protocol: default: https 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: query schema: type: string example: gcgzw5rz2xovp84b4vha3a40 required: true security: - accessToken: [] components: securitySchemes: accessToken: description: Plex Authentication Token type: apiKey in: query name: X-Plex-Token paths: /: get: tags: - Server summary: Get Server Capabilities description: Get 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 /companions: get: servers: - url: 'https://plex.tv/api/v2/' tags: - Plex summary: Get Companions Data description: Get Companions Data operationId: getCompanionsData responses: '200': description: Companions Data content: application/json: schema: type: array items: type: object required: - identifier - baseURL - title - linkURL - provides - token properties: identifier: type: string example: tv.plex.sonos baseURL: type: string example: 'https://sonos.plex.tv' format: uri title: type: string example: Sonos linkURL: type: string example: 'https://sonos.plex.tv/link' provides: type: string example: 'client,player' token: type: string description: The plex authtoken used to identify with '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 /friends: get: servers: - url: 'https://plex.tv/api/v2/' tags: - Plex summary: Get list of friends of the user logged in description: Get friends of provided auth token. operationId: getUserFriends responses: '200': description: Friends Data content: application/json: schema: type: array items: title: Friend type: object examples: - email: username@email.com friendlyName: exampleUser home: true id: 0 restricted: false sharedServers: [] sharedSources: [] status: accepted thumb: 'https://plex.tv/users/7d1916e0d8f6e76b/avatar?c=1694481578' title: username123 username: username123 uuid: 7d1916e0d8f6e76b required: - email - friendlyName - home - id - restricted - sharedServers - sharedSources - status - thumb - title - username - uuid properties: email: type: string format: email example: username@email.com description: The account email address friendlyName: examples: - exampleUser - null type: - string - 'null' description: The account full name home: type: boolean description: If the account is a Plex Home user id: type: integer format: int32 description: The Plex account ID restricted: type: boolean default: false description: If the account is a Plex Home managed user sharedServers: type: array items: type: object sharedSources: type: array items: type: object status: examples: - accepted enum: - accepted description: Current friend request status thumb: type: string example: 'https://plex.tv/users/7d1916e0d8f6e76b/avatar?c=1694481578' format: uri description: URL of the account thumbnail title: type: string example: username123 description: The title of the account (username or friendly name) username: type: string example: username123 description: The account username uuid: type: string example: 7d1916e0d8f6e76b description: The account Universally Unique Identifier (UUID) '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 /geoip: get: servers: - url: 'https://plex.tv/api/v2/' security: [] tags: - Plex summary: Get Geo Data description: Returns the geolocation and locale data of the caller operationId: getGeoData responses: '200': description: Gets the geo location data of the user content: application/json: schema: title: GeoData type: object description: Geo location data examples: - code: VI continent_code: NA country: United States Virgin Islands city: Amsterdam european_union_member: true time_zone: America/St_Thomas postal_code: 802 in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: Saint Thomas coordinates: '18.3381, -64.8941' required: - code - continent_code - country - city - european_union_member - time_zone - postal_code - in_privacy_restricted_country - in_privacy_restricted_region - subdivisions - coordinates properties: code: type: string description: The ISO 3166-1 alpha-2 code of the country. example: VI continent_code: type: string description: The continent code where the country is located. example: NA country: type: string description: The official name of the country. example: United States Virgin Islands city: type: string description: The name of the city. example: Amsterdam european_union_member: type: boolean description: Indicates if the country is a member of the European Union. example: true default: false time_zone: type: string description: The time zone of the country. example: America/St_Thomas postal_code: type: integer description: The postal code of the location. example: 802 in_privacy_restricted_country: type: boolean description: Indicates if the country has privacy restrictions. example: true default: false in_privacy_restricted_region: type: boolean description: Indicates if the region has privacy restrictions. example: true default: false subdivisions: type: string description: The name of the primary administrative subdivision. example: Saint Thomas coordinates: type: string description: 'The geographical coordinates (latitude, longitude) of the location.' example: '18.3381, -64.8941' '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 /home: get: tags: - Plex summary: Get Plex Home Data description: 'Retrieves the home data for the authenticated user, including details like home ID, name, guest access information, and subscription status.' operationId: getHomeData responses: '200': description: Home Data content: application/json: schema: type: object properties: id: type: number example: 1841489 name: type: string example: Blindkitty38's home guestUserID: type: number example: 58815432 guestUserUUID: type: string example: f3df4e01bfca0787 guestEnabled: type: boolean subscription: type: boolean '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 /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: This request is useful to determine if the server is online or offline operationId: get-server-identity security: [] 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 '408': description: Request Timeout content: application/json: schema: type: object properties: code: type: integer example: 408 message: type: string example: The server timed out waiting for the request. /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 parameters: - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json - name: X-Plex-Container-Start in: query description: | The index of the first item to return. If not specified, the first item will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 0 schema: type: integer format: int32 default: 0 example: 0 required: false - name: X-Plex-Container-Size in: query description: | The number of items to return. If not specified, all items will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 50 schema: type: integer format: int32 default: 50 example: 50 required: false 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: get-all-libraries 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 required: - size - allowSync - title1 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 example: 1556281940 description: Unix epoch datetime format: int32 createdAt: type: - integer example: 1556281940 description: Unix epoch datetime format: int32 scannedAt: type: - integer example: 1556281940 description: Unix epoch datetime format: int32 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/{sectionKey}': 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: get-library-details parameters: - name: sectionKey description: | The unique key of the Plex library. Note: This is unique in the context of the Plex server. in: path schema: type: integer format: int32 example: 9518 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: Delete a library using a specific section id operationId: deleteLibrary parameters: - name: sectionKey description: | The unique key of the Plex library. Note: This is unique in the context of the Plex server. in: path schema: type: integer format: int32 example: 9518 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/watchlist/{filter}': servers: - url: 'https://metadata.provider.plex.tv' description: The plex metadata provider server get: tags: - Watchlist summary: Get User Watchlist description: Get User Watchlist operationId: get-watch-list parameters: - name: filter description: Filter in: path required: true schema: type: string enum: - all - available - released - name: sort description: | In the format "field:dir". Available fields are "watchlistedAt" (Added At), "titleSort" (Title), "originallyAvailableAt" (Release Date), or "rating" (Critic Rating). "dir" can be "asc" or "desc" in: query required: false schema: type: string - name: libtype description: | The type of library to filter. Can be "movie" or "show", or all if not present. in: query required: false schema: type: string enum: - movie - show - name: maxresults description: | The number of items to return. If not specified, all items will be returned. If the number of items exceeds the limit, the response will be paginated. in: query required: false schema: type: integer format: int32 - name: includeCollections description: | include collections in the results in: query required: false schema: type: integer enum: - 1 - 0 - name: includeExternalMedia description: | include external media in the results in: query required: false schema: type: integer enum: - 1 - 0 - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json - name: X-Plex-Container-Start in: query description: | The index of the first item to return. If not specified, the first item will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 0 schema: type: integer format: int32 default: 0 example: 0 required: false - name: X-Plex-Container-Size in: query description: | The number of items to return. If not specified, all items will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 50 schema: type: integer format: int32 default: 50 example: 50 required: false - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true responses: '200': description: Watchlist Data content: application/json: schema: type: object properties: librarySectionID: type: string librarySectionTitle: type: string offset: type: integer format: int32 totalSize: type: integer format: int32 identifier: type: string size: type: integer format: int32 Metadata: type: array items: type: object properties: art: type: string guid: type: string key: type: string ratingKey: type: string studio: type: string tagline: type: string type: type: string thumb: type: string addedAt: type: integer format: int32 duration: type: integer format: int32 publicPagesURL: type: string slug: type: string userState: type: boolean title: type: string contentRating: type: string originallyAvailableAt: type: string format: date year: type: integer format: int32 Image: type: array items: type: object properties: alt: type: string type: type: string url: type: string banner: type: string rating: type: number expiresAt: type: integer format: int32 originalTitle: type: string audienceRating: type: number audienceRatingImage: type: string ratingImage: type: string imdbRatingCount: type: integer format: int32 subtype: type: string theme: type: string leafCount: type: integer format: int32 childCount: type: integer format: int32 isContinuingSeries: type: boolean skipChildren: type: boolean availabilityId: type: string streamingMediaId: type: string playableKey: 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 '/library/sections/{sectionKey}/{tag}': get: tags: - Library summary: Get Library Items operationId: get-library-items 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: sectionKey description: | The unique key of the Plex library. Note: This is unique in the context of the Plex server. in: path schema: type: integer format: int32 example: 9518 required: true - 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 - name: includeGuids in: query description: | Adds the Guids object to the response schema: type: integer enum: - 0 - 1 example: 1 required: false - name: includeMeta in: query description: | Adds the Meta object to the response schema: type: integer enum: - 0 - 1 example: 1 required: false - name: type in: query description: | The type of media to retrieve. 1 = movie 2 = show 3 = season 4 = episode E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries schema: type: integer enum: - 1 - 2 - 3 - 4 example: 2 required: true - name: X-Plex-Container-Start in: query description: | The index of the first item to return. If not specified, the first item will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 0 schema: type: integer format: int32 default: 0 example: 0 required: false - name: X-Plex-Container-Size in: query description: | The number of items to return. If not specified, all items will be returned. If the number of items exceeds the limit, the response will be paginated. By default this is 50 schema: type: integer format: int32 default: 50 example: 50 required: false - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json 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 - string examples: - 1 - watchlist 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/{sectionKey}/refresh': get: tags: - Library summary: Refresh Metadata Of The Library description: | This endpoint Refreshes all the Metadata of the library. operationId: get-refresh-library-metadata parameters: - name: sectionKey description: | The unique key of the Plex library. Note: This is unique in the context of the Plex server. in: path schema: type: integer format: int32 example: 9518 required: true - name: force description: Force the refresh even if the library is already being refreshed. in: query schema: type: integer example: 0 enum: - 0 - 1 required: false 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/{sectionKey}/search': get: tags: - Library summary: Search Library operationId: get-search-library 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: sectionKey description: | The unique key of the Plex library. Note: This is unique in the context of the Plex server. in: path schema: type: integer format: int32 example: 9518 required: true - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json - name: type in: query description: | The type of media to retrieve. 1 = movie 2 = show 3 = season 4 = episode E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries schema: type: integer enum: - 1 - 2 - 3 - 4 example: 2 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 Metadata by RatingKey description: | This endpoint will return the metadata of a library item specified with the ratingKey. operationId: get-meta-data-by-rating-key parameters: - name: ratingKey in: path description: the id of the library item to return the children of. schema: type: integer example: 9518 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}/banner': get: tags: - Media summary: Get Banner Image description: Gets the banner image of the media item operationId: get-banner-image parameters: - name: ratingKey in: path description: the id of the library item to return the children of. schema: type: integer example: 9518 required: true - name: width in: query required: true schema: type: integer example: 396 - name: height in: query required: true schema: type: integer example: 396 - name: minSize in: query required: true schema: type: integer example: 1 - name: upscale in: query required: true schema: type: integer example: 1 - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true responses: '200': description: Successful response returning an image headers: X-Plex-Protocol: description: Version of the Plex protocol schema: type: string example: '1.0' Content-Type: description: The MIME type of the returned content schema: type: string example: image/jpeg Connection: description: Connection type schema: type: string example: Keep-Alive Keep-Alive: description: Keep-Alive header with timeout value schema: type: string example: timeout=20 Content-Encoding: description: Content encoding method schema: type: string example: gzip X-Plex-Content-Original-Length: description: Original length of the uncompressed content schema: type: integer format: int32 example: 92476 X-Plex-Content-Compressed-Length: description: Length of the compressed content schema: type: integer format: int32 example: 92483 Content-Length: description: Length of the response content schema: type: integer format: int32 example: 92483 Cache-Control: description: Cache control directives schema: type: string example: max-age=259200 Date: description: Date and time the response was generated schema: type: string format: date-time example: 'Tue, 03 Sep 2024 10:48:05 GMT' content: image/jpeg: schema: type: string format: binary '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}/thumb': get: tags: - Media summary: Get Thumb Image description: Gets the thumbnail image of the media item operationId: get-thumb-image parameters: - name: ratingKey in: path description: the id of the library item to return the children of. schema: type: integer example: 9518 required: true - name: width in: query required: true schema: type: integer example: 396 - name: height in: query required: true schema: type: integer example: 396 - name: minSize in: query required: true schema: type: integer example: 1 - name: upscale in: query required: true schema: type: integer example: 1 - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true responses: '200': description: Successful response returning an image headers: X-Plex-Protocol: description: Version of the Plex protocol schema: type: string example: '1.0' Content-Type: description: The MIME type of the returned content schema: type: string example: image/jpeg Connection: description: Connection type schema: type: string example: Keep-Alive Keep-Alive: description: Keep-Alive header with timeout value schema: type: string example: timeout=20 Content-Encoding: description: Content encoding method schema: type: string example: gzip X-Plex-Content-Original-Length: description: Original length of the uncompressed content schema: type: integer format: int32 example: 92476 X-Plex-Content-Compressed-Length: description: Length of the compressed content schema: type: integer format: int32 example: 92483 Content-Length: description: Length of the response content schema: type: integer format: int32 example: 92483 Cache-Control: description: Cache control directives schema: type: string example: max-age=259200 Date: description: Date and time the response was generated schema: type: string format: date-time example: 'Tue, 03 Sep 2024 10:48:05 GMT' content: image/jpeg: schema: type: string format: binary '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 - name: includeElements description: | Adds additional elements to the response. Supported types are (Stream) in: query schema: type: string required: false examples: include-stream: value: Stream include-stream-otheritem: value: 'Stream,OtherItem' include-stream-otheritem-anotheritem: value: 'Stream,OtherItem,AnotherItem' 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/all/top: get: tags: - Library summary: Get Top Watched Content description: | This endpoint will return the top watched content from libraries of a certain type operationId: getTopWatchedContent parameters: - name: type in: query description: | The type of media to retrieve. 1 = movie 2 = show 3 = season 4 = episode E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries schema: type: integer enum: - 1 - 2 - 3 - 4 example: 2 required: true - name: includeGuids in: query description: | Adds the Guids object to the response schema: type: integer required: false example: 1 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 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' slug: type: string example: waterloo-road 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.' index: type: integer example: 1 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 leafCount: type: integer example: 222 viewedLeafCount: type: integer example: 100 childCount: type: integer example: 13 addedAt: type: integer format: int32 example: 1705637164 updatedAt: type: integer format: int32 example: 1705637165 globalViewCount: type: integer example: 80 audienceRatingImage: type: string example: 'rottentomatoes://image.rating.upright' 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' 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' User: type: array items: type: object properties: id: type: integer format: int32 example: 220 '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 /resources: get: servers: - url: 'https://plex.tv/api/v2/' tags: - Plex summary: Get Server Resources description: Get Plex server access tokens and server connections operationId: get-server-resources 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: query schema: type: string example: gcgzw5rz2xovp84b4vha3a40 required: true - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true - name: includeHttps in: query description: Include Https entries in the results schema: type: integer format: int32 enum: - 0 - 1 example: 1 default: 0 - name: includeRelay in: query description: | Include Relay addresses in the results E.g: https://10-0-0-25.bbf8e10c7fa20447cacee74cd9914cde.plex.direct:32400 schema: type: integer format: int32 enum: - 0 - 1 example: 1 default: 0 - name: includeIPv6 in: query description: Include IPv6 entries in the results schema: type: integer format: int32 enum: - 0 - 1 example: 1 default: 0 - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json responses: '200': description: List of Plex Devices. This includes Plex hosted servers and clients content: application/json: schema: type: array items: title: PlexDevice type: object required: - name - product - productVersion - platform - platformVersion - device - clientIdentifier - createdAt - lastSeenAt - provides - ownerId - sourceTitle - publicAddress - accessToken - owned - home - synced - relay - presence - httpsRequired - publicAddressMatches - dnsRebindingProtection - natLoopbackSupported - connections properties: name: type: string product: type: string productVersion: type: string platform: type: - 'null' - string platformVersion: type: - 'null' - string device: type: - 'null' - string clientIdentifier: type: string createdAt: type: string format: date-time lastSeenAt: type: string format: date-time provides: type: string ownerId: description: ownerId is null when the device is owned by the token used to send the request type: - 'null' - integer sourceTitle: type: - 'null' - string publicAddress: type: string accessToken: type: string owned: type: boolean home: type: boolean synced: type: boolean relay: type: boolean presence: type: boolean httpsRequired: type: boolean publicAddressMatches: type: boolean dnsRebindingProtection: type: boolean natLoopbackSupported: type: boolean connections: type: array items: type: object required: - protocol - address - port - uri - local - relay - IPv6 properties: protocol: type: string address: type: string port: type: number uri: type: string local: type: boolean relay: type: boolean IPv6: type: boolean '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 /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: query schema: type: string example: gcgzw5rz2xovp84b4vha3a40 required: true - name: X-Plex-Product in: query required: false schema: type: string example: Plex Web responses: '200': description: Requests a new pin id used in the authentication flow content: application/json: schema: type: object x-examples: Example 1: id: 373040866 code: 7RQZ product: '0' trusted: false qr: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: 9klpwueublnfbvlx95w83ah9 location: code: NL european_union_member: true continent_code: EU country: The Netherlands city: Breda time_zone: Europe/Amsterdam postal_code: '4814' in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: North Brabant coordinates: '51.5869, 4.7471' expiresIn: 876 createdAt: '2024-07-16T17:03:05Z' expiresAt: '2024-07-16T17:18:05Z' authToken: null newRegistration: null title: AuthPinContainer examples: - id: 308667304 code: 7RQZ product: '0' trusted: false qr: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: string location: code: VI continent_code: NA country: United States Virgin Islands city: Amsterdam european_union_member: true time_zone: America/St_Thomas postal_code: 802 in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: Saint Thomas coordinates: '18.3381, -64.8941' expiresIn: 876 createdAt: '2024-07-16T17:03:05Z' expiresAt: '2024-07-16T17:18:05Z' authToken: null newRegistration: null required: - id - code - product - trusted - qr - clientIdentifier - location - expiresIn - createdAt - expiresAt properties: id: type: integer example: 308667304 code: type: string example: 7RQZ product: type: string example: '0' trusted: type: boolean default: false qr: type: string example: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: type: string description: The X-Client-Identifier used in the request location: title: GeoData type: object description: Geo location data examples: - code: VI continent_code: NA country: United States Virgin Islands city: Amsterdam european_union_member: true time_zone: America/St_Thomas postal_code: 802 in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: Saint Thomas coordinates: '18.3381, -64.8941' required: - code - continent_code - country - city - european_union_member - time_zone - postal_code - in_privacy_restricted_country - in_privacy_restricted_region - subdivisions - coordinates properties: code: type: string description: The ISO 3166-1 alpha-2 code of the country. example: VI continent_code: type: string description: The continent code where the country is located. example: NA country: type: string description: The official name of the country. example: United States Virgin Islands city: type: string description: The name of the city. example: Amsterdam european_union_member: type: boolean description: Indicates if the country is a member of the European Union. example: true default: false time_zone: type: string description: The time zone of the country. example: America/St_Thomas postal_code: type: integer description: The postal code of the location. example: 802 in_privacy_restricted_country: type: boolean description: Indicates if the country has privacy restrictions. example: true default: false in_privacy_restricted_region: type: boolean description: Indicates if the region has privacy restrictions. example: true default: false subdivisions: type: string description: The name of the primary administrative subdivision. example: Saint Thomas coordinates: type: string description: 'The geographical coordinates (latitude, longitude) of the location.' example: '18.3381, -64.8941' expiresIn: type: integer example: 876 description: 'The number of seconds this pin expires, by default 900 seconds' default: 900 createdAt: type: string example: '2024-07-16T17:03:05Z' format: date-time expiresAt: type: string format: date-time example: '2024-07-16T17:18:05Z' authToken: type: 'null' newRegistration: type: 'null' '400': description: Bad Request response when the X-Plex-Client-Identifier is missing content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: integer example: 1000 message: type: string example: X-Plex-Client-Identifier is missing status: type: integer example: 400 '/pins/{pinID}': get: servers: - url: 'https://plex.tv/api/v2/' security: [] tags: - Plex summary: Get Access Token by PinId description: Retrieve an Access Token from Plex.tv after the Pin has been authenticated operationId: getTokenByPinId 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: query schema: type: string example: gcgzw5rz2xovp84b4vha3a40 required: true - name: pinID description: The PinID to retrieve an access token for in: path required: true schema: type: integer responses: '200': description: The Pin with a non-null authToken when it has been verified by the user content: application/json: schema: type: object x-examples: Example 1: id: 373040866 code: 7RQZ product: '0' trusted: false qr: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: 9klpwueublnfbvlx95w83ah9 location: code: NL european_union_member: true continent_code: EU country: The Netherlands city: Breda time_zone: Europe/Amsterdam postal_code: '4814' in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: North Brabant coordinates: '51.5869, 4.7471' expiresIn: 876 createdAt: '2024-07-16T17:03:05Z' expiresAt: '2024-07-16T17:18:05Z' authToken: null newRegistration: null title: AuthPinContainer examples: - id: 308667304 code: 7RQZ product: '0' trusted: false qr: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: string location: code: VI continent_code: NA country: United States Virgin Islands city: Amsterdam european_union_member: true time_zone: America/St_Thomas postal_code: 802 in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: Saint Thomas coordinates: '18.3381, -64.8941' expiresIn: 876 createdAt: '2024-07-16T17:03:05Z' expiresAt: '2024-07-16T17:18:05Z' authToken: null newRegistration: null required: - id - code - product - trusted - qr - clientIdentifier - location - expiresIn - createdAt - expiresAt properties: id: type: integer example: 308667304 code: type: string example: 7RQZ product: type: string example: '0' trusted: type: boolean default: false qr: type: string example: 'https://plex.tv/api/v2/pins/qr/7RQZ' clientIdentifier: type: string description: The X-Client-Identifier used in the request location: title: GeoData type: object description: Geo location data examples: - code: VI continent_code: NA country: United States Virgin Islands city: Amsterdam european_union_member: true time_zone: America/St_Thomas postal_code: 802 in_privacy_restricted_country: true in_privacy_restricted_region: true subdivisions: Saint Thomas coordinates: '18.3381, -64.8941' required: - code - continent_code - country - city - european_union_member - time_zone - postal_code - in_privacy_restricted_country - in_privacy_restricted_region - subdivisions - coordinates properties: code: type: string description: The ISO 3166-1 alpha-2 code of the country. example: VI continent_code: type: string description: The continent code where the country is located. example: NA country: type: string description: The official name of the country. example: United States Virgin Islands city: type: string description: The name of the city. example: Amsterdam european_union_member: type: boolean description: Indicates if the country is a member of the European Union. example: true default: false time_zone: type: string description: The time zone of the country. example: America/St_Thomas postal_code: type: integer description: The postal code of the location. example: 802 in_privacy_restricted_country: type: boolean description: Indicates if the country has privacy restrictions. example: true default: false in_privacy_restricted_region: type: boolean description: Indicates if the region has privacy restrictions. example: true default: false subdivisions: type: string description: The name of the primary administrative subdivision. example: Saint Thomas coordinates: type: string description: 'The geographical coordinates (latitude, longitude) of the location.' example: '18.3381, -64.8941' expiresIn: type: integer example: 876 description: 'The number of seconds this pin expires, by default 900 seconds' default: 900 createdAt: type: string example: '2024-07-16T17:03:05Z' format: date-time expiresAt: type: string format: date-time example: '2024-07-16T17:18:05Z' authToken: type: 'null' newRegistration: type: 'null' '400': description: Bad Request response when the X-Plex-Client-Identifier is missing content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: integer example: 1000 message: type: string example: X-Plex-Client-Identifier is missing status: type: integer example: 400 '404': description: Not Found or Expired content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: integer example: 1020 message: type: string example: Code not found or expired example: errors: - code: 1020 message: Code not found or expired /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: '204': 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 in: query description: | The type of media to retrieve. 1 = movie 2 = show 3 = season 4 = episode E.g. A movie library will not return anything with type 3 as there are no seasons for movie libraries schema: type: integer enum: - 1 - 2 - 3 - 4 example: 2 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 /media/providers: get: tags: - Server summary: Get Media Providers description: Retrieves media providers and their features from the Plex server. operationId: get-media-providers parameters: - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true responses: '200': description: Media providers and their features content: application/json: schema: type: object properties: MediaContainer: type: object properties: size: type: integer allowCameraUpload: type: boolean allowChannelAccess: 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 livetv: type: integer machineIdentifier: type: string musicAnalysis: type: integer myPlex: type: boolean myPlexMappingState: type: string myPlexSigninState: type: string myPlexSubscription: type: boolean myPlexUsername: type: string offlineTranscode: type: integer ownerFeatures: type: string platform: type: string platformVersion: type: string pluginHost: type: boolean pushNotifications: type: boolean readOnlyLibraries: type: boolean streamingBrainABRVersion: type: integer streamingBrainVersion: type: integer sync: type: boolean transcoderActiveVideoSessions: type: integer transcoderAudio: type: boolean transcoderLyrics: type: boolean transcoderSubtitles: type: boolean transcoderVideo: type: boolean transcoderVideoBitrates: type: string transcoderVideoQualities: type: string transcoderVideoResolutions: type: string updatedAt: type: integer updater: type: boolean version: type: string voiceSearch: type: boolean MediaProvider: type: array items: type: object properties: identifier: type: string title: type: string types: type: string protocols: type: string Feature: type: array items: type: object properties: key: type: string type: type: string Directory: type: array items: type: object properties: hubKey: type: string title: type: string agent: type: string language: type: string refreshing: type: boolean scanner: type: string uuid: type: string id: type: string key: type: string type: type: string subtype: type: string updatedAt: type: integer scannedAt: type: integer Pivot: type: array items: type: object properties: id: type: string key: type: string type: type: string title: type: string context: type: string symbol: 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 /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 /statistics/resources: get: tags: - Statistics summary: Get Resources Statistics description: This will return the resources for the server operationId: getResourcesStatistics 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: Resource Statistics content: application/json: schema: type: object properties: MediaContainer: type: object properties: size: type: integer format: int32 example: 5497 StatisticsResources: type: array items: type: object properties: timespan: type: integer example: 6 at: type: integer example: 1718384427 hostCpuUtilization: type: number format: float example: 1.276 processCpuUtilization: type: number format: float example: 0.025 hostMemoryUtilization: type: number format: float example: 17.026 processMemoryUtilization: type: number format: float example: 0.493 '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/bandwidth: get: tags: - Statistics summary: Get Bandwidth Statistics description: This will return the bandwidth statistics for the server operationId: getBandwidthStatistics 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: Bandwidth 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' StatisticsBandwidth: type: array items: type: object properties: accountID: type: integer format: int32 example: 238960586 deviceID: type: integer format: int32 example: 208 timespan: type: integer example: 6 at: type: integer format: int32 example: 1718387650 lan: type: boolean example: true bytes: type: integer example: 22 '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 parameters: - name: sort description: | Sorts the results by the specified field followed by the direction (asc, desc) in: query schema: type: string required: false examples: viewed-at-descending: value: 'viewedAt:desc' viewed-at-ascending: value: 'viewedAt:asc' rating-descending: value: 'rating:desc' rating-ascending: value: 'rating:asc' - name: accountId description: | Filter results by those that are related to a specific users id in: query schema: type: integer required: false example: 1 - name: filter description: | Filters content by field and direction/equality (Unknown if viewedAt is the only supported column) in: query schema: type: object pattern: '^[A-Za-z][A-Za-z0-9]*[>=<]{0,2}$' example: viewed-at-greater-than: value: viewedAt> viewed-at-greater-than-or-equal-to: value: viewedAt>=> viewed-at-less-than: value: viewedAt< required: false examples: ViewedAt: value: viewedAt>=1704862818 - name: librarySectionID description: | Filters the results based on the id of a valid library section in: query schema: type: integer required: false example: 12 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 [Release] entry for this version will have the `state` set to `skipped`.' required: false in: query schema: type: integer enum: - 0 - 1 example: 1 responses: '200': description: If the update process started correctly '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 '500': description: If the update process failed to start '/video/:/transcode/universal/start.mpd': get: tags: - Video summary: Start Universal Transcode description: Begin a Universal Transcode Session operationId: startUniversalTranscode parameters: - name: hasMDE description: Whether the media item has MDE required: true in: query schema: type: number example: 1 - name: path description: The path to the media item to transcode required: true in: query schema: type: string example: /library/metadata/23409 - name: mediaIndex description: The index of the media item to transcode required: true in: query schema: type: number example: 0 - name: partIndex description: The index of the part to transcode required: true in: query schema: type: number example: 0 - name: protocol description: The protocol to use for the transcode session required: true in: query schema: type: string example: hls - name: fastSeek description: Whether to use fast seek or not required: false in: query schema: type: number example: 0 - name: directPlay description: Whether to use direct play or not required: false in: query schema: type: number example: 0 - name: directStream description: Whether to use direct stream or not required: false in: query schema: type: number example: 0 - name: subtitleSize description: The size of the subtitles required: false in: query schema: type: number example: 100 - name: subtites description: The subtitles required: false in: query schema: type: string example: burn - name: audioBoost description: The audio boost required: false in: query schema: type: number example: 100 - name: location description: The location of the transcode session required: false in: query schema: type: string example: lan - name: mediaBufferSize description: The size of the media buffer required: false in: query schema: type: number example: 102400 - name: session description: The session ID required: false in: query schema: type: string example: zvcage8b7rkioqcm8f4uns4c - name: addDebugOverlay description: Whether to add a debug overlay or not required: false in: query schema: type: number example: 0 - name: autoAdjustQuality description: Whether to auto adjust quality or not required: false in: query schema: type: number example: 0 responses: '200': description: The transcode session has started '400': description: 'Bad Request - A parameter was not specified, or was specified incorrectly.' '401': description: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: number example: 1001 message: type: string example: User could not be authenticated status: type: number example: 401 /user: get: servers: - url: 'https://plex.tv/api/v2/' tags: - Authentication summary: Get User Data By Token description: Get the User data from the provided X-Plex-Token operationId: getUserDetails parameters: - name: X-Plex-Token in: query description: Plex Authentication Token schema: type: string example: CV5xoxjTpFKUzBTShsaf required: true - name: Accept in: header required: false schema: type: string enum: - application/json - application/xml example: application/json responses: '200': description: Logged in user details content: application/json: schema: title: UserPlexAccount type: object examples: - adsConsent: true adsConsentReminderAt: '2019-08-24T14:15:22Z' adsConsentSetAt: '2019-08-24T14:15:22Z' anonymous: false authToken: CxoUzBTSV5hsxjTpFKaf backupCodesCreated: false confirmed: false country: US email: username@email.com emailOnlyAuth: false experimentalFeatures: false friendlyName: friendlyUsername entitlements: [] guest: false hasPassword: true home: false homeAdmin: false homeSize: 1 id: 13692262 joinedAt: 1721154902 locale: null mailingListActive: false mailingListStatus: subscribed maxHomeSize: 15 pastSubscriptions: - id: string mode: string renewsAt: string endsAt: '1556281940' canceled: '0' gracePeriod: '0' onHold: '0' canReactivate: '0' canUpgrade: '0' canDowngrade: '0' canConvert: '0' type: plexpass transfer: string state: ended billing: - internalPaymentMethod: string paymentMethodId: string pin: string profile: - autoSelectAudio: true defaultAudioLanguage: ja defaultSubtitleLanguage: en autoSelectSubtitle: 1 defaultSubtitleAccessibility: 1 defaultSubtitleForced: 0 watchedIndicator: 1 mediaReviewsVisibility: 0 protected: false rememberExpiresAt: 1722364046 restricted: false roles: - string scrobbleTypes: '' services: - identifier: metadata-dev endpoint: 'https://epg.provider.plex.tv' token: DjoMtqFAGRL1uVtCyF1dKIorTbShJeqv secret: string status: online subscription: features: - Android - Dolby Vision active: true subscribedAt: '2021-04-12T18:21:12Z' status: Inactive paymentService: string plan: string subscriptionDescription: string subscriptions: - features: - Android - Dolby Vision active: true subscribedAt: '2021-04-12T18:21:12Z' status: Inactive paymentService: string plan: string thumb: 'https://plex.tv/users/a4f43c1ebfde43a5/avatar?c=8372075101' title: UsernameTitle trials: - {} twoFactorEnabled: false username: Username uuid: dae343c1f45beb4f required: - adsConsent - adsConsentReminderAt - adsConsentSetAt - anonymous - authToken - backupCodesCreated - confirmed - country - email - emailOnlyAuth - experimentalFeatures - friendlyName - entitlements - guest - hasPassword - home - homeAdmin - homeSize - id - joinedAt - locale - mailingListActive - mailingListStatus - maxHomeSize - profile - protected - rememberExpiresAt - restricted - scrobbleTypes - services - subscription - subscriptionDescription - subscriptions - thumb - title - twoFactorEnabled - username - uuid properties: adsConsent: type: - boolean - 'null' description: Unknown adsConsentReminderAt: type: - string - 'null' description: Unknown format: date-time adsConsentSetAt: type: - string - 'null' description: Unknown format: date-time anonymous: type: - boolean - 'null' description: Unknown default: false authToken: type: string description: The account token example: CxoUzBTSV5hsxjTpFKaf backupCodesCreated: type: boolean description: If the two-factor authentication backup codes have been created default: false confirmed: type: boolean description: If the account has been confirmed default: false country: type: string description: The account country example: US maxLength: 2 minLength: 2 email: type: string description: The account email address format: email example: username@email.com emailOnlyAuth: type: boolean description: If login with email only is enabled default: false experimentalFeatures: type: boolean description: If experimental features are enabled default: false friendlyName: type: string description: Your account full name example: friendlyUsername entitlements: type: array description: List of devices your allowed to use with this account items: type: string example: '[]' guest: type: boolean description: If the account is a Plex Home guest user default: false hasPassword: type: boolean description: If the account has a password default: true home: type: boolean description: If the account is a Plex Home user default: false homeAdmin: type: boolean description: If the account is the Plex Home admin default: false homeSize: type: integer description: The number of accounts in the Plex Home example: 1 format: int32 id: type: integer description: The Plex account ID example: 13692262 format: int32 joinedAt: type: integer description: Unix epoch datetime the account joined Plex format: int32 example: 1721154902 locale: type: - string - 'null' description: The account locale mailingListActive: type: boolean description: If you are subscribed to the Plex newsletter default: false mailingListStatus: description: Your current mailing list status enum: - active - unsubscribed maxHomeSize: type: integer description: The maximum number of accounts allowed in the Plex Home example: 15 format: int32 pin: type: string description: '[Might be removed] The hashed Plex Home PIN ' deprecated: true profile: title: UserProfile type: object required: - defaultAudioLanguage - defaultSubtitleLanguage properties: autoSelectAudio: type: boolean example: true default: true description: If the account has automatically select audio and subtitle tracks enabled defaultAudioLanguage: type: - string - 'null' example: ja description: The preferred audio language for the account defaultSubtitleLanguage: type: - string - 'null' example: en description: The preferred subtitle language for the account autoSelectSubtitle: example: 1 description: 'The auto-select subtitle mode (0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled)' enum: - 0 - 1 defaultSubtitleAccessibility: enum: - 0 - 1 example: 1 description: 'The subtitles for the deaf or hard-of-hearing (SDH) searches mode (0 = Prefer non-SDH subtitles, 1 = Prefer SDH subtitles, 2 = Only show SDH subtitles, 3 = Only shown non-SDH subtitles)' defaultSubtitleForced: enum: - 0 - 1 example: 0 description: 'The forced subtitles searches mode (0 = Prefer non-forced subtitles, 1 = Prefer forced subtitles, 2 = Only show forced subtitles, 3 = Only show non-forced subtitles)' watchedIndicator: enum: - 0 - 1 example: 1 mediaReviewsVisibility: enum: - 0 - 1 type: integer example: 0 protected: type: boolean description: If the account has a Plex Home PIN enabled default: false rememberExpiresAt: type: integer description: Unix epoch datetime the authtoken expires format: int32 example: 1722364046 restricted: type: boolean description: If the account is a Plex Home managed user default: false roles: type: array description: '[Might be removed] List of account roles. Plexpass membership listed here' items: type: string scrobbleTypes: type: string description: Unknown services: type: array items: type: object required: - identifier - endpoint - token - secret - status properties: identifier: type: string example: metadata-dev endpoint: type: string example: 'https://epg.provider.plex.tv' format: uri token: type: - string - 'null' example: DjoMtqFAGRL1uVtCyF1dKIorTbShJeqv secret: type: - string - 'null' status: example: online enum: - online - offline subscription: description: If the account’s Plex Pass subscription is active title: Subscription type: object properties: features: description: List of features allowed on your Plex Pass subscription type: array items: enum: - Android - Dolby Vision - Android - PiP - CU Sunset - HRK_enable_EUR - TREBLE-show-features - ad-countdown-timer - adaptive_bitrate - amazon-loop-debug - avod-ad-analysis - avod-new-media - blacklist_get_signin - client-radio-stations - cloudflare-turnstile-required - collections - comments_and_replies_push_notifications - community_access_plex_tv - companions_sonos - custom-home-removal - disable_home_user_friendships - disable_sharing_friendships - drm_support - exclude restrictions - federated-auth - friend_request_push_notifications - guided-upgrade - home - increase-password-complexity - ios14-privacy-banner - iterable-notification-tokens - keep-payment-method - kevin-bacon - korea-consent - le_isrg_root_x1 - lets_encrypt - lightning-dvr-pivot - live-tv-support-incomplete-segments - livetv - metadata_search - new_plex_pass_prices - news-provider-sunset-modal - photos-favorites - photos-metadata-edition - pms_health - radio - rate-limit-client-token - scrobbling-service-plex-tv - shared_server_notification - shared_source_notification - signin_with_apple - spring_serve_ad_provider - transcoder_cache - tuner-sharing - two-factor-authentication - unsupportedtuners - upgrade-3ds2 - vod-schema - vod_cloudflare - watch-together-invite - web_server_dashboard active: description: If the account's Plex Pass subscription is active type: boolean example: true subscribedAt: description: Date the account subscribed to Plex Pass type: - string - 'null' example: '2021-04-12T18:21:12Z' status: description: String representation of subscriptionActive example: Inactive enum: - Inactive - Active paymentService: description: Payment service used for your Plex Pass subscription type: - string - 'null' plan: description: Name of Plex Pass subscription plan type: - string - 'null' subscriptionDescription: type: - string - 'null' description: Description of the Plex Pass subscription subscriptions: type: array items: title: Subscription type: object properties: features: description: List of features allowed on your Plex Pass subscription type: array items: enum: - Android - Dolby Vision - Android - PiP - CU Sunset - HRK_enable_EUR - TREBLE-show-features - ad-countdown-timer - adaptive_bitrate - amazon-loop-debug - avod-ad-analysis - avod-new-media - blacklist_get_signin - client-radio-stations - cloudflare-turnstile-required - collections - comments_and_replies_push_notifications - community_access_plex_tv - companions_sonos - custom-home-removal - disable_home_user_friendships - disable_sharing_friendships - drm_support - exclude restrictions - federated-auth - friend_request_push_notifications - guided-upgrade - home - increase-password-complexity - ios14-privacy-banner - iterable-notification-tokens - keep-payment-method - kevin-bacon - korea-consent - le_isrg_root_x1 - lets_encrypt - lightning-dvr-pivot - live-tv-support-incomplete-segments - livetv - metadata_search - new_plex_pass_prices - news-provider-sunset-modal - photos-favorites - photos-metadata-edition - pms_health - radio - rate-limit-client-token - scrobbling-service-plex-tv - shared_server_notification - shared_source_notification - signin_with_apple - spring_serve_ad_provider - transcoder_cache - tuner-sharing - two-factor-authentication - unsupportedtuners - upgrade-3ds2 - vod-schema - vod_cloudflare - watch-together-invite - web_server_dashboard active: description: If the account's Plex Pass subscription is active type: boolean example: true subscribedAt: description: Date the account subscribed to Plex Pass type: - string - 'null' example: '2021-04-12T18:21:12Z' status: description: String representation of subscriptionActive example: Inactive enum: - Inactive - Active paymentService: description: Payment service used for your Plex Pass subscription type: - string - 'null' plan: description: Name of Plex Pass subscription plan type: - string - 'null' thumb: type: string description: URL of the account thumbnail format: uri example: 'https://plex.tv/users/a4f43c1ebfde43a5/avatar?c=8372075101' title: type: string description: The title of the account (username or friendly name) example: UsernameTitle twoFactorEnabled: type: boolean description: If two-factor authentication is enabled default: false username: type: string description: The account username example: Username uuid: type: string description: The account UUID example: dae343c1f45beb4f '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 /users/signin: post: servers: - url: 'https://plex.tv/api/v2/' security: [] tags: - Authentication summary: Get User SignIn Data description: Sign in user with username and password and return user data with Plex authentication token operationId: post-users-sign-in-data 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: query schema: type: string example: gcgzw5rz2xovp84b4vha3a40 required: true requestBody: content: application/x-www-form-urlencoded: schema: type: object required: - login - password properties: login: type: string format: email example: username@email.com password: type: string format: password example: password123 rememberMe: type: boolean default: false description: Login credentials responses: '201': description: Returns the user account data with a valid auth token content: application/json: schema: allOf: - title: UserPlexAccount type: object examples: - adsConsent: true adsConsentReminderAt: '2019-08-24T14:15:22Z' adsConsentSetAt: '2019-08-24T14:15:22Z' anonymous: false authToken: CxoUzBTSV5hsxjTpFKaf backupCodesCreated: false confirmed: false country: US email: username@email.com emailOnlyAuth: false experimentalFeatures: false friendlyName: friendlyUsername entitlements: [] guest: false hasPassword: true home: false homeAdmin: false homeSize: 1 id: 13692262 joinedAt: 1721154902 locale: null mailingListActive: false mailingListStatus: subscribed maxHomeSize: 15 pastSubscriptions: - id: string mode: string renewsAt: string endsAt: '1556281940' canceled: '0' gracePeriod: '0' onHold: '0' canReactivate: '0' canUpgrade: '0' canDowngrade: '0' canConvert: '0' type: plexpass transfer: string state: ended billing: - internalPaymentMethod: string paymentMethodId: string pin: string profile: - autoSelectAudio: true defaultAudioLanguage: ja defaultSubtitleLanguage: en autoSelectSubtitle: 1 defaultSubtitleAccessibility: 1 defaultSubtitleForced: 0 watchedIndicator: 1 mediaReviewsVisibility: 0 protected: false rememberExpiresAt: 1722364046 restricted: false roles: - string scrobbleTypes: '' services: - identifier: metadata-dev endpoint: 'https://epg.provider.plex.tv' token: DjoMtqFAGRL1uVtCyF1dKIorTbShJeqv secret: string status: online subscription: features: - Android - Dolby Vision active: true subscribedAt: '2021-04-12T18:21:12Z' status: Inactive paymentService: string plan: string subscriptionDescription: string subscriptions: - features: - Android - Dolby Vision active: true subscribedAt: '2021-04-12T18:21:12Z' status: Inactive paymentService: string plan: string thumb: 'https://plex.tv/users/a4f43c1ebfde43a5/avatar?c=8372075101' title: UsernameTitle trials: - {} twoFactorEnabled: false username: Username uuid: dae343c1f45beb4f required: - adsConsent - adsConsentReminderAt - adsConsentSetAt - anonymous - authToken - backupCodesCreated - confirmed - country - email - emailOnlyAuth - experimentalFeatures - friendlyName - entitlements - guest - hasPassword - home - homeAdmin - homeSize - id - joinedAt - locale - mailingListActive - mailingListStatus - maxHomeSize - profile - protected - rememberExpiresAt - restricted - scrobbleTypes - services - subscription - subscriptionDescription - subscriptions - thumb - title - twoFactorEnabled - username - uuid properties: adsConsent: type: - boolean - 'null' description: Unknown adsConsentReminderAt: type: - string - 'null' description: Unknown format: date-time adsConsentSetAt: type: - string - 'null' description: Unknown format: date-time anonymous: type: - boolean - 'null' description: Unknown default: false authToken: type: string description: The account token example: CxoUzBTSV5hsxjTpFKaf backupCodesCreated: type: boolean description: If the two-factor authentication backup codes have been created default: false confirmed: type: boolean description: If the account has been confirmed default: false country: type: string description: The account country example: US maxLength: 2 minLength: 2 email: type: string description: The account email address format: email example: username@email.com emailOnlyAuth: type: boolean description: If login with email only is enabled default: false experimentalFeatures: type: boolean description: If experimental features are enabled default: false friendlyName: type: string description: Your account full name example: friendlyUsername entitlements: type: array description: List of devices your allowed to use with this account items: type: string example: '[]' guest: type: boolean description: If the account is a Plex Home guest user default: false hasPassword: type: boolean description: If the account has a password default: true home: type: boolean description: If the account is a Plex Home user default: false homeAdmin: type: boolean description: If the account is the Plex Home admin default: false homeSize: type: integer description: The number of accounts in the Plex Home example: 1 format: int32 id: type: integer description: The Plex account ID example: 13692262 format: int32 joinedAt: type: integer description: Unix epoch datetime the account joined Plex format: int32 example: 1721154902 locale: type: - string - 'null' description: The account locale mailingListActive: type: boolean description: If you are subscribed to the Plex newsletter default: false mailingListStatus: description: Your current mailing list status enum: - active - unsubscribed maxHomeSize: type: integer description: The maximum number of accounts allowed in the Plex Home example: 15 format: int32 pin: type: string description: '[Might be removed] The hashed Plex Home PIN ' deprecated: true profile: title: UserProfile type: object required: - defaultAudioLanguage - defaultSubtitleLanguage properties: autoSelectAudio: type: boolean example: true default: true description: If the account has automatically select audio and subtitle tracks enabled defaultAudioLanguage: type: - string - 'null' example: ja description: The preferred audio language for the account defaultSubtitleLanguage: type: - string - 'null' example: en description: The preferred subtitle language for the account autoSelectSubtitle: example: 1 description: 'The auto-select subtitle mode (0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled)' enum: - 0 - 1 defaultSubtitleAccessibility: enum: - 0 - 1 example: 1 description: 'The subtitles for the deaf or hard-of-hearing (SDH) searches mode (0 = Prefer non-SDH subtitles, 1 = Prefer SDH subtitles, 2 = Only show SDH subtitles, 3 = Only shown non-SDH subtitles)' defaultSubtitleForced: enum: - 0 - 1 example: 0 description: 'The forced subtitles searches mode (0 = Prefer non-forced subtitles, 1 = Prefer forced subtitles, 2 = Only show forced subtitles, 3 = Only show non-forced subtitles)' watchedIndicator: enum: - 0 - 1 example: 1 mediaReviewsVisibility: enum: - 0 - 1 type: integer example: 0 protected: type: boolean description: If the account has a Plex Home PIN enabled default: false rememberExpiresAt: type: integer description: Unix epoch datetime the authtoken expires format: int32 example: 1722364046 restricted: type: boolean description: If the account is a Plex Home managed user default: false roles: type: array description: '[Might be removed] List of account roles. Plexpass membership listed here' items: type: string scrobbleTypes: type: string description: Unknown services: type: array items: type: object required: - identifier - endpoint - token - secret - status properties: identifier: type: string example: metadata-dev endpoint: type: string example: 'https://epg.provider.plex.tv' format: uri token: type: - string - 'null' example: DjoMtqFAGRL1uVtCyF1dKIorTbShJeqv secret: type: - string - 'null' status: example: online enum: - online - offline subscription: description: If the account’s Plex Pass subscription is active title: Subscription type: object properties: features: description: List of features allowed on your Plex Pass subscription type: array items: enum: - Android - Dolby Vision - Android - PiP - CU Sunset - HRK_enable_EUR - TREBLE-show-features - ad-countdown-timer - adaptive_bitrate - amazon-loop-debug - avod-ad-analysis - avod-new-media - blacklist_get_signin - client-radio-stations - cloudflare-turnstile-required - collections - comments_and_replies_push_notifications - community_access_plex_tv - companions_sonos - custom-home-removal - disable_home_user_friendships - disable_sharing_friendships - drm_support - exclude restrictions - federated-auth - friend_request_push_notifications - guided-upgrade - home - increase-password-complexity - ios14-privacy-banner - iterable-notification-tokens - keep-payment-method - kevin-bacon - korea-consent - le_isrg_root_x1 - lets_encrypt - lightning-dvr-pivot - live-tv-support-incomplete-segments - livetv - metadata_search - new_plex_pass_prices - news-provider-sunset-modal - photos-favorites - photos-metadata-edition - pms_health - radio - rate-limit-client-token - scrobbling-service-plex-tv - shared_server_notification - shared_source_notification - signin_with_apple - spring_serve_ad_provider - transcoder_cache - tuner-sharing - two-factor-authentication - unsupportedtuners - upgrade-3ds2 - vod-schema - vod_cloudflare - watch-together-invite - web_server_dashboard active: description: If the account's Plex Pass subscription is active type: boolean example: true subscribedAt: description: Date the account subscribed to Plex Pass type: - string - 'null' example: '2021-04-12T18:21:12Z' status: description: String representation of subscriptionActive example: Inactive enum: - Inactive - Active paymentService: description: Payment service used for your Plex Pass subscription type: - string - 'null' plan: description: Name of Plex Pass subscription plan type: - string - 'null' subscriptionDescription: type: - string - 'null' description: Description of the Plex Pass subscription subscriptions: type: array items: title: Subscription type: object properties: features: description: List of features allowed on your Plex Pass subscription type: array items: enum: - Android - Dolby Vision - Android - PiP - CU Sunset - HRK_enable_EUR - TREBLE-show-features - ad-countdown-timer - adaptive_bitrate - amazon-loop-debug - avod-ad-analysis - avod-new-media - blacklist_get_signin - client-radio-stations - cloudflare-turnstile-required - collections - comments_and_replies_push_notifications - community_access_plex_tv - companions_sonos - custom-home-removal - disable_home_user_friendships - disable_sharing_friendships - drm_support - exclude restrictions - federated-auth - friend_request_push_notifications - guided-upgrade - home - increase-password-complexity - ios14-privacy-banner - iterable-notification-tokens - keep-payment-method - kevin-bacon - korea-consent - le_isrg_root_x1 - lets_encrypt - lightning-dvr-pivot - live-tv-support-incomplete-segments - livetv - metadata_search - new_plex_pass_prices - news-provider-sunset-modal - photos-favorites - photos-metadata-edition - pms_health - radio - rate-limit-client-token - scrobbling-service-plex-tv - shared_server_notification - shared_source_notification - signin_with_apple - spring_serve_ad_provider - transcoder_cache - tuner-sharing - two-factor-authentication - unsupportedtuners - upgrade-3ds2 - vod-schema - vod_cloudflare - watch-together-invite - web_server_dashboard active: description: If the account's Plex Pass subscription is active type: boolean example: true subscribedAt: description: Date the account subscribed to Plex Pass type: - string - 'null' example: '2021-04-12T18:21:12Z' status: description: String representation of subscriptionActive example: Inactive enum: - Inactive - Active paymentService: description: Payment service used for your Plex Pass subscription type: - string - 'null' plan: description: Name of Plex Pass subscription plan type: - string - 'null' thumb: type: string description: URL of the account thumbnail format: uri example: 'https://plex.tv/users/a4f43c1ebfde43a5/avatar?c=8372075101' title: type: string description: The title of the account (username or friendly name) example: UsernameTitle twoFactorEnabled: type: boolean description: If two-factor authentication is enabled default: false username: type: string description: The account username example: Username uuid: type: string description: The account UUID example: dae343c1f45beb4f - type: object required: - pastSubscriptions - trials properties: pastSubscriptions: type: array items: title: PastSubscription type: object required: - id - mode - renewsAt - endsAt - canceled - gracePeriod - onHold - canReactivate - canUpgrade - canDowngrade - canConvert - type - transfer - state - billing properties: id: type: - string - 'null' mode: type: - string - 'null' renewsAt: oneOf: - type: - integer example: 1556281940 description: Unix epoch datetime format: int32 - type: 'null' endsAt: oneOf: - type: - integer example: 1556281940 description: Unix epoch datetime format: int32 - type: 'null' canceled: type: boolean example: false default: false gracePeriod: type: boolean example: false default: false onHold: type: boolean example: false default: false canReactivate: type: boolean example: false default: false canUpgrade: type: boolean example: false default: false canDowngrade: type: boolean example: false default: false canConvert: type: boolean example: false default: false type: type: string example: plexpass transfer: type: - string - 'null' state: example: ended enum: - ended billing: type: object required: - internalPaymentMethod - paymentMethodId properties: internalPaymentMethod: type: object paymentMethodId: type: - integer - 'null' trials: type: array items: type: object '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 - name: Watchlist description: | API Calls that perform operations with Plex Media Server Watchlists