Plex Library API

openapi: 3.2.0
info:
  title: Plex Media Server Library API
  version: '1.2.2

    '
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: "# API Info\n## Content Types\nThe API supports responses in both XML and JSON, and clients can request one or the other using the standard `Accept` HTTP header. The default is XML, so JSON will only be returned if it's explicitly requested (`Accept: application/json`).  New applications should use JSON.\n\nThroughout the docs, it's common for a examples to be given in JSON only since the JSON response would be preferred for new applications.\n\n## Headers\n\nPMS accept a variety of custom headers that follow the pattern `X-Plex-{name}`. The full set of headers isn't enumerated here since some may only apply to certain endpoints, but common headers that can be included on all requests include:\n\n| Header | Description | Sample |\n| --- | --- | --- |\n| X-Plex-Client-Identifier | An opaque identifier unique to the client | abc123 |\n| X-Plex-Token | An authentication token, obtained from plex.tv | XXXXXXXXXXXX |\n| X-Plex-Product | The name of the client product | Plex for Roku |\n| X-Plex-Version | The version of the client application | 2.4.1 |\n| X-Plex-Platform | The platform of the client | Roku |\n| X-Plex-Platform-Version | The version of the platform | 4.3 build 1057 |\n| X-Plex-Device | A relatively friendly name for the client device | Roku 3 |\n| X-Plex-Model | A potentially less friendly identifier for the device model | 4200X |\n| X-Plex-Device-Vendor | The device vendor | Roku |\n| X-Plex-Device-Name | A friendly name for the client | Living Room TV |\n| X-Plex-Marketplace | The marketplace on which the client application is distributed  | googlePlay |\n\n`X-Plex-Client-Identifier` is typically required, as is `X-Plex-Token` for authentication.\n\nThere's no standard way to send non-ASCII values as HTTP headers. We attempt to recognize and parse UTF-8 and ISO-8859-1. If you're sending something that may include non-ASCII characters (often `X-Plex-Device-Name`), use UTF-8 if possible.\n\nThese are referred to as headers throughout documentation, but all `X-Plex-` headers can also be sent as query string arguments.\n\n## Auth\n\nMost endpoints require token based authentication, and the token is expected to be sent in the `X-Plex-Token` header. Tokens are obtained from plex.tv.  See the <a href=\"#section/API-Info/Authenticating-with-Plex\">Authenticating with Plex</a> section.\n\n## Paths and Keys\n\nMany parts of the API reference things that can be fetched by their `key`. These keys follow a sort of relative URL resolution pattern. Some examples will help clarify.\n\n- For a request to `/library/sections` that includes an item with a `key` of `home` in the response, that item can be fetched at `/library/sections/home`.\n- For a request to `/library/sections/home` that includes an item with a `key` of `/library/metadata/deadbeef` in the response, that item can be fetched at `/library/metadata/deadbeef`.\n\nWe say this follows a \"sort of\" relative URL resolution pattern because all requests are treated as though they have a trailing slash.\n\n```\n/library/sections/ + home => /library/sections/home\n/library/sections + home => /library/sections/home\n/library/sections + /library/sections/home => /library/sections/home\n```\n\nJust like URL resolution, keys may contain absolute URLs as well, especially absolute `https://...` URLs or custom `view://...` URLs. In these cases the key resolved by simply using it, the parent is irrelevant.\n\nAlso note that the features described in this API can generally be present at a different paths. The `/media/providers` path defines where all features can be found.  Note that a PMS can contain multiple providers which will be enumerated here.  For simplicity, these docs use the most common, default paths. But when we say that `/library/sections/{id}` is part of the API, what we really mean is that a endpoint exists which is composed of the key for the `content` feature and the key for the library section.\n\nFinally, it's worth noting that many paths can potentially be discovered by walking API responses and fetching `key`s, but paths that aren't documented here aren't part of the API contract, they just happen to exist for a particular provider. For example, a particular content directory might include a directory with `key={baseLibraryPath}/genre`. That's not an official part of the API that's guaranteed to exist for every content directory, it's just a `key` that happened to exist within that content directory.\n\n## Types\n\nMany elements throughout the API have a `type` attribute. These types are meant to give helpful information, such as whether something is a movie library or a TV show library.  Some API elements rely on a type number so both are provided below\n\n### List of Metadata Types\n\n| Type Name | Type Number |\n| -- | -- |\n| `movie` | 1 |\n| `show` | 2 |\n| `season` | 3 |\n| `episode` | 4 |\n| `trailer` | 5 |\n| `person` | 7 |\n| `artist` | 8 |\n| `album` | 9 |\n| `track` | 10 |\n| `clip` | 12 |\n| `photo` | 13 |\n| `photoalbum` | 14 |\n| `playlist` | 15 |\n| `playlistfolder` | 16 |\n| `collection` | 18 |\n\nWhen an element has both `type` and `key` attributes, the type describes what will be returned when fetching that key. Some types will return a list of other elements. That list may have a `Meta` element describing the specific types within the list. Consider the following examples:\n\n```json\n[\n  {\n    \"key\": \"/foo\",\n    \"type\": \"movie\",\n    \"title\": \"A Movie\"\n  },\n  {\n    \"key\": \"/bar\",\n    \"type\": \"collection\",\n    \"title\": \"My Favorite Movies\"\n  },\n  {\n    \"key\": \"/baz\",\n    \"type\": \"show\",\n    \"title\": \"A Show\"\n  }\n]\n```\n\nIn each case, the `type` describes what will be returned when fetching the key. One exception is the `/children` key for parents like shows and seasons. It will return a list of children even though the `type` describes the parent.\n\nSome elements may also include an optional `subtype` attribute. The subtype is meant to be a refinement of the type, not a completely different type. One test is trying to explain the type in natural language. `type=\"clip\" subtype=\"news\"` passes the test that \"This is a clip, a news clip specifically.\" Another test is considering the client UI. A client should be functional if it ignores the subtype, and optimized if it respects it. If `type=\"track\" subtype=\"podcast\"`, a client can successfully play the podcast in an audio player based purely on the type, but it may tweak the display or which advanced playback controls are visible based on the subtype.\n\n### List of Metadata Subtypes\n\n- `podcast`\n- `webshow`\n- `news`\n- `photo`\n\n#### Collection Subtypes\n\n- `movie`\n- `show`\n- `artist`\n- `album`\n\n#### Extras Subtypes\n\n- `trailer`\n- `deletedScene`\n- `interview`\n- `musicVideo`\n- `behindTheScenes`\n- `sceneOrSample`\n- `liveMusicVideo`\n- `lyricMusicVideo`\n- `concert`\n- `featurette`\n- `short`\n- `other`\n\n## Sources\n\nSource URIs and attributes make it possible to uniquely reference content outside the local server context without requiring a fixed url. This might be desirable when showing related albums from a friend's shared media server, building a universal play queue, or returning aggregated hubs that span multiple providers. Source components are immutable and act as pointers to a single item or directory in the Plex ecosystem.\n\nA source URI from a media server uses the `server` scheme while a cloud provider uses the `provider` scheme.\n\n```\nserver://{SERVER_ID}/{PROVIDER_ID}/{PATH}\nprovider://{PROVIDER_ID}/{PATH}\n```\n\nAs a single regular expression, that's:\n\n```\n/^(server|provider):\\/\\/([a-fA-F0-9-]+)?\\/?([^/]+)([^\\?]+)\\??(.*)?/\n```\n\nThe server id is the server's `machineIdentifier`. The provider id is the provider's `identifier`. The rest of the path represents the path of the content at the provider and may include additional query parameters like `X-Plex-` headers or media query syntax for sorts and filters.\n\nSome examples may be helpful:\n\n```\nserver://546684a3d18ac5c39037360ec9ce900b7af9cc36/com.plexapp.plugins.library/library/metadata/2814936\nprovider://tv.plex.provider.podcasts/library/sections/audio/all\n```\n\nThe `source` attribute has the same structure as the source URI, but omits the path.\n\n```\n{SOURCE_TYPE}://{SOURCE_ID}/{PROVIDER_ID?}\n```\n```\n/^(server|provider):\\/\\/([a-fA-F0-9-]+)?\\/?([^/]+)$/\n```\n\n```\nsource=\"server://546684a3d18ac5c39037360ec9ce900b7af9cc36/com.plexapp.plugins.library\"\nsource=\"provider://tv.plex.provider.podcasts\"\n```\n\nSource attributes can be used as a base and combined with `key` or other root-relative path components to construct unique source URIs.\n\n## Pagination\n\nMany endpoints that return a list of items support pagination.  Additionally some endpoints will force pagination and limit number of elements returned if the client attempts to request all items. To request a specific subset of data, add two headers to specify the starting offset and the number of desired items.\n\n- **X-Plex-Container-Start** - The desired starting offset\n- **X-Plex-Container-Size** - The desired number of items\n\nBoth headers should be sent in order to request paginated content. Note that it's possible to request a size of 0 on supported endpoints in order to learn the total size without actually getting any content.\n\nThe response **must** be checked to see if the response is in fact paginated. The response might not be paginated at all, or it might include a different number of items than what was requested. A paginated response will include the headers:\n\n- **X-Plex-Container-Start** - The offset of the first returned item\n- **X-Plex-Container-Total-Size** - The **total** size of the collection (optional but typically present)\n\nThe response body will also typically include pagination info. If the response is a `MediaContainer`, then it will have `offset` and `size` attributes representing the start index and the number of items in the current response along with an optional `totalSize` attribute for the total number of elements in the collection.\n\n```\nHTTP/1.1 200 OK\nX-Plex-Container-Start: 2\nX-Plex-Container-Total-Size: 5\nContent-Type: application/xml\n\n{\n  \"MediaContainer\": {\n    \"size\": 3,\n    \"totalSize\": 5,\n    \"offset\": 2,\n    \"Metadata\" : [\n      …\n    ]\n  }\n}\n```\n\nRather than requesting a page starting at an index, it is also possible in some lists to request a page centered on a specific item in the list.\n\n- **X-Plex-Container-Focus-Key** - The key of an item to center on\n- **X-Plex-Container-Size** - The desired number of items\n\nThe requested size is respected regardless of the position of the focus item in the list. If the item is at the start of the list and 10 items are requested, 9 items in the response will be after the item. If the item is in the middle of the list and 10 items are requested, 4 items will be before the item and 5 items will be after.\n\nEndpoints that support rich media queries also have a `limit` parameter that interacts with pagination. Sending `limit` in a query string limits the desired number of items, much like the `X-Plex-Container-Size` header. There are two major differences:\n\n1. When using `limit`, the total size of the collection is not returned. The minimum of the limit and the actual total size will be returned as the total size.\n2. The request may be more efficient when using `limit`, since the total size doesn't have to be known.\n\nIf the total size of the collection isn't needed, use `limit`, since the request may be more efficient.\n\nNote that `limit` and `X-Plex-Container-Size` aren't mutually exclusive. You can page within the results that are bounded by the limit. If you want a total of 1000 items from a collection of many thousands of items, but you want to page through them 20 at a time, you'd use `limit=1000&X-Plex-Container-Size=20&X-Plex-Container-Start=0`.\n\n## API Versioning\n\nPMS has never used API versioning before the creation of this document.  The first published API is considered `1.0` with the API prior to publication considered `0.0`.  A client species its version via the `X-Plex-Pms-Api-Version` header on requests.  If no header is provided, the version `0.0` is assumed.\n\n### API Changes\n - 1.0.0 (Supported in PMS >= 1.41.9)\n  - Added `/downloadQueue` endpoints.\n  - Public release of API.\n  - The `includeFields` parameter has been renamed to `includeOptionalFields`.  The `includeFields` parameter now means \"include only these fields\" where in the past it meant \"please add these fields you wouldn't normally include.\"  This was changed to be consistent with the cloud provider API.\n\n\n- 1.1.0 (Supported in PMS >= 1.42.0)\n  - Added ability to filter '/media/providers/metadata' endpoint by metadata types (PM-3702)\n  - Changed `types` in `/playlists/{playlistId}/items` to array of integers.\n  - Document the `/photo/:/transcode` endpoints\n  - Fixed serialization of MetadataType objects for '/media/providers/metadata' calls.\n\n\n- 1.1.1 (Supported in PMS >= 1.42.2)\n  - Added 'metadataAgentProviderGroupId' query param to create and edit library section (PM-3577)\n  - Fixed Add library section method type.\n\n\n- 1.2.0 (Supported in PMS >= 1.43.0)\n  - Added 'squareArt' as additional element type for image assets (PM-2959)\n  - Added `/media/providers/metadata` endpoints (PM-1012)\n  - Added delete method for /library/metadata/{id}/{element} (PM-4094)\n  - Added documentation for Metadata-type Media Providers (PM-3051)\n\n\n- 1.2.1 (Supported in PMS >= 1.43.1)\n  - Added `/tv.plex.providers.epg.{identifier}:{deviceId}` endpoints (PM-4017)\n  - Added new state to itemsGeneratorItems endpoint (PM-3475)\n\n\n- 1.2.2 (Supported in PMS >= 1.43.2)\n  - Added `audioLayout` endpoint (PM-5118)\n  - Added `videoCodec`, `audioCodec`, and `subtitleCodec` endpoints (PM-5117)\n\n## Response Customization\n\nMany endpoints allow the data that is included in the response to be tailored to exactly what the client wants. This is possible by either specifying things that should be excluded or the set of things that should be included.  PMS's ability to include/exclude elements and fields is currently limited but expanding so this should be used with care.\n\nAttributes can be customized by using a query string arg of either `excludeFields` or `includeFields`. This single parameter should be a comma-separated list of attribute names. For example, a request with `excludeFields=summary,tagline` is asking for the summary and title attributes to be left off any metadata items while the `includeFields` parameter indicated that only the specified fields should be included.\n\nChild elements can be customized by using a query string arg of either `excludeElements` or `includeElements`. This single parameter should be a comma-separated list of element names. For example, a request with `excludeElements=Media` is asking for the `Media` elements to be omitted while the `includeElements` parameter indicated that only the specified elements should be included.\n\nIn addition to the above are the parameters `includeOptionalFields` and `includeOptionalElements`.  These indicate that the fields/elements which are not normally included should be included in this request.  One example is `includeOptionalElements=musicAnalysis` on metadata will include the `musicAnalysis` parameter which can be large and typically not needed by a client.\n\nTrimming the response to only include what a client will actually use can result in much better performance, especially in large collections.  Increasingly these are being used to select which data is fetched from the database.  So if a client knows it will only ever use a few parameters from a request, it should specify those with `includeFields`.\n\nNote that these inclusions/exclusions are treated as requests, not guarantees. Some endpoints will disregard them completely, and others may ignore them for specific items and insist on returning data that the client didn't necessarily ask for.\n\n## Media Providers\n\nMedia providers are general purpose entities which supply media to Plex clients. Their API describes the Plex Media Server API, via a set of features on the \"root\" endpoint of the provider. Media provider can be hosted by a media server or in the cloud, linked to a specific Plex account. This section explains media providers generally, and then provides the specific server-hosted APIs around media providers.\n\n### Client Guide to Media Providers\n\nThe philosophy behind media providers in general is to allow a common API between cloud servers and PMS, since the APIs are nearly identical to a normal PMS. The general guidelines are:\n- Consume `/media/providers` instead of `/library/sections`\n\n  The new providers endpoint give you a list of all providers exported by a server and their features. Remember that the library itself is considered a (very rich) provider! This change will also require changing the client to not hardwire paths on the server, but rather read them from the feature keys directly (e.g. scrobble and rating endpoints).\n\n- Gate management functionality on the `manage` feature\n\n  Server libraries allow management (e.g. media deletion). The correct way to gate this functionality is via the manage feature.\n\n- Make sure key construction is correct for things like genre lists\n\n  For example, `/library/sections/x/genre` returns a relative key for each genre, but there's nothing which says that the `key` can't be an absolute URL. This is why servers pass back `fastKey` separately so as to not break clients which don't do key construction correctly. Media providers do not pass back `fastKey`, but assume clients will be doing correct key construction.\n\n- Don't call `/library/sections/X/filters|sorts`\n\n  You can get all that information (and more) in a single call by hitting `/library/sections/X?includeDetails=1`. Media providers include the extra information by default.\n\n- Respect the Type keys in `/library/sections/x`\n\n  The top-level type pivots have their own keys, which should be used over the old \"just append `/all` to the path and add the type\" approach. Not only is this more flexible, it also allows for \"virtual\" pivots, like music videos inside a music library.\n\n- Look for the `skipChildren`/`skipParent` attributes for shows\n\n  Because of things like Podcasts, single-season shows can now be made to skip seasons. This is indicated by a `skipChildren` attribute on the show, or a `skipParent` attribute on an episode. If this is set on a show, the client should use `/grandchildren` instead of `/children` in the show's key.\n\n### Features\n\nThe list of supported features, along with the API endpoints each feature represents is shown in the following list. Note that each feature can define a custom endpoint URL, so it doesn't have to match the server API exactly.\n\n- **search**: This feature implies that it supports search via the provided key.\n\n- **metadata**: This feature implies that it supports metadata endpoint.  For example, if the `key` were `/library/metadata` then the endpoints `/library/metadata/X`, `/library/metadata/X/children` and `/library/metadata/X/grandchildren` would be supported. This endpoint family allows browsing a hierarchical tree of media (e.g. show to episodes, or artist to tracks).\n\n- **content**: This feature implies that the provider exposes a content catalog, in the form of libraries to browse (grid of content), or discover (via hubs). Each entry in the content feature can contain:\n\n  - `hubKey`: This implies it supports a discovery endpoint with hubs.\n  - `key`: This implies it supports a content catalog.\n  - `icon`: Optional, specifies the icon used for a content directory.\n\n  Each content feature can contain one or both of these keys, depending on the structure. More details on the various combinations are provided below.\n\n- **match**: The match feature is used to match a piece of media to the provider's content catalog via a set of hints. As a specific example, you might pass in a title hint of \"Attack of the 50 Foot Woman\" and a year hint of 1958 for the movie type. The provider would then use all the hints to attempt to match to entries in its catalog.\n\n- **manage**: The manage feature implies a whole host of endpoints around _changing_ data inside a library (e.g. editing fields, customizing artwork, etc.). This feature is generally only available on an actual server and generally only to the admin.\n\n- **timeline**: The timeline feature implies that the provider wants to receive timeline (playback notifications) requests from a client at the endpoint defined by `key`. The feature may additionally specify the `scrobbleKey` and `unscrobbleKey` attributes, which represent the endpoints which allow marking a piece of media played or unplayed.\n\n- **rate**: This feature implies the provider supports the endpoint which allows rating content.\n\n- **playqueue**: This feature implies the provider supports the play queue family of endpoints. The `flavor` attribute further specifies the subset; the only supported flavor is currently `full`.\n\n- **playlist**: This feature implies the provider supports the playlist family of endpoints. If `readonly` is set, that means that the provider only allows listing and playing playlists (via play queue API), not actually creating or editing them.\n\n- **subscribe**: This provider allows media subscriptions to be created.  If the flavor is `record` then media can be recorded from this library (such as DVR).  If the flavor is `download` then the user is allowed to download from this library.\n\n- **promoted**: This feature allows the provider to supply an endpoint that will return a collection of \"promoted\" hubs that many clients show on a user's home screen.\n\n- **continuewatching**: This feature allows the provider to supply an endpoint that will return a hub for merging into a global Continue Watching hub.\n\n- **collection**: This feature implies the provider supports the collection family of endpoints.\n\n- **actions**\n  - **removeFromContinueWatching** - Action to remove an item from continue watching\n\n- **imagetranscoder** - This feature implies the provider supports the image transcoder endpoints used to scale images for clients where memory and processor is at a premium\n\n- **queryParser** - This feature implies the provider supports the media queries language below\n\n- **grid** - This feature implies the provider supports displaying metadata in a grid over time (such as live TV)\n\n##### Home discovery and browsable libraries\n\nShown in the example in [/media/providers](#tag/Provider/operation/getMediaProviders), in this media provider the first content directory is an item with only `hubKey`, meaning it only providers discovery hubs. This is the set of hubs covering the whole library which contains continue watching, recently added, recommendations, etc. It's essentially \"landing page\" for the provider.\n\nThe subsequent directories also have a browse `key`, which means they provide a list view of the content with options for filtering and sorting.  EPG providers may have only the `key` and no `hubKey`.\n\n##### Minimal provider\n\nThere's no requirement to provide the content feature, given that there are two other ways to access content within a provider: search and match. The former can contribute to global search, whereas the latter is used for things like the DVR engine; once media subscriptions are set up, they look for matching content using the match feature, and examined using the metadata feature.\n\n##### Deeper Hierarchies\n\nIf you examine an app like Spotify, you'll see many of the concepts here apply to their content hierarchy. Their content screens are either grids or hubs. But one notable difference is that the content hierarchy runs a bit deeper than the examples we've examined thus far. For example, one of the top-level selections is \"Genres & Moods\". Diving into one of the genres leads to a discovery area with different hubs for popular playlists, artists, and albums from the genre. Selecting a mood leads to a grid with popular playlists for the mood. In order to support this sort of hierarchy, we need an extension to the regular library, which is a *content directory*. This allows us to nest content, without losing any of the power and features—for example, the grid with popular playlists could list filters and sorts specific for that grid. This is power you simply don't have with the old channel architecture.\n\n##### Extensions to regular libraries\n\nThis section examines extensions to plain libraries which content providers can use, and which clients need to be aware of.\n\n- **Nested content directories**: In regular libraries, there are fixed types of directories (e.g. shows, or music albums). In content providers, we want to have the ability to display other types of things (e.g. stations, or moods, or genres) as first-class things in a grid or discovery layout. Here's an example of what a nested content directory looks like. Given the `type` of content, the client knows that this directory should be treated like a content directory feature entry.\n\n  ```json\n  {\n    \"Directory\":[\n      {\n        \"key\":\"foo\",\n        \"hubKey\":\"foo2\",\n        \"type\":\"content\",\n        \"aspectRatio\":\"1:1\",\n        \"title\":\"Genres and Moods\"\n      }\n    ]\n  }\n  ```\n\n- **Aspect ratio hint**: Because the entities listed in content directories can be arbitrary, it's important to tell the client some information about how they should be displayed. The `thumb` attribute contains no information about aspect ratio, so clients make assumptions based upon known types (e.g. movies are 2:3, episode thumbs are 16:9, etc.). This attributes allows the provider to specify exactly the aspect ratio of the thing being displayed.\n\n## Metadata Providers\n\nThis section describes the specific Media Providers which supply the `metadata` feature. These providers can be created and used in Plex Media Server to supply metadata to items inside Movie and TV Show libraries (music libraries are currently not supported).\n\n### Common Request Headers\n\nThere are a few headers which are common to both the Metadata and Match features. These can be passed as either headers or query parameters.\n\n| Header | Support Required? | Description |\n|--------|-------------------|-------------|\n| X-Plex-Language | No | IETF language tag including the region subtag (e.g. 'en-US', 'de-DE'). Used for localization.\n| X-Plex-Country | No | ISO 3166 two-letter country code. Used primarily to define the country for certification data, or can be used to determine release dates for the specific country.\n| X-Plex-Container-Size | Yes | For paged requests. This determines what the maximum container size should be of a single response.\n| X-Plex-Container-Start | Yes | For paged requests. This determines the starting index for the paged request.\n\n### Response Paging\n\nCertain responses may contain a large number of objects. The consumer may want to limit the size of the MediaContainer by paging through them using the `X-Plex-Container-Size` and `X-Plex-Container-Start` headers/params. Responses should them limit the object count inside the MediaContainer to `X-Plex-Container-Size` and start at the index provided by `X-Plex-Container-Start`.\n\nSee the [Pagination](#pagination) section for more details on how paging works.\n\nThe only two endpoints that require mandatory paging are the Metadata `/children` and `/grandchildren` endpoints as these will potentially contain many items. Passing no paging headers here should only return the first 20 Metadata objects.\n\n### Common return codes\n\nIt is important to return the correct HTTP return codes.\n\n| Code | Common Name | Description |\n|------|-------------|-------------|\n| 200 | OK | An response for an item or match is successfully returned |\n| 404 | Not Found | If an item with the requested ratingKey is not found (Metadata feature only) |\n| 400 | Bad Request | A request was made which cannot be fulfilled because the request is malformed |\n| 500 | Internal Server Error | A request was made which cannot be fulfilled because the server encountered an internal error |\n\n### Response Customization (Optional)\n\nThere may be cases where a reduced response is wanted, i.e. we only want to return specific attributes or exclude specific attributes. These are handled with `includeFields`, `excludeFields`, `includeElements` and `excludeElements`.\n\nInformation on its use can be found in the [Response Customization](#response-customization).\n\nYou may wish to add support for this to keep response sizes down, however it is not required and you can safely ignore when these parameters are passed.\n\n### Metadata Feature\n\nThis is a path to retrieve metadata for a specific piece of content by its id.\n\nIt is called by making a `GET` request to the path defined by the `Metadata` feature inside the root of your provider with the `ratingKey` of the metadata item.\n\nFor example, the request may be something like `GET http://localhost/library/metadata/tmdb-movie-123` which should return a [Metadata Object](#metadata-object) for the item with the `ratingKey` of \"tmdb-movie-123\".\n\nSee some [Example Responses](#example-responses)\n\n#### Supported Query Parameters\n\nThere are some query parameters available to media provider to augment the responses. Not all of these are required to be supported by all providers, support requirement is detailed in the below table.\n\n| Param | Type | Support Required? | Description |\n|-------|------|-------------------|-------------|\n| `includeChildren` | integer (1/0) | Yes (TV Shows/Seasons only) | Returns a [Children Object](#children-object) when the metadata type has direct child objects (e.g. a TV Show should return Season Children)\n| `episodeOrder` | string | No | When making a request that returns seasons in the response, pass back the appropriate season items for the requested [SeasonType id](#seasontype-array-optional). It is expected that if no seasons exist for the requested episodeOrder, that no season data should be returned.\n\n#### Image endpoint (Recommended)\n\nThe Metadata feature should also provide a `/images` path for calls to specific items, e.g. `/library/metadata/tmdb-movie-123/images`. This endpoint should return a [MediaContainer](#mediacontainer) object containing and [Image Array](#image-array-highly-recommended) of all the available image assets for that item.\n\nExample:\n\n```json\n{\n  \"MediaContainer\": {\n    \"offset\": 0,\n    \"totalSize\": 3,\n    \"identifier\": \"tv.plex.provider.metadata\",\n    \"size\": 3,\n    \"Image\": [\n      {\n        \"type\": \"coverPoster\",\n        \"url\": \"https://image.tmdb.org/t/p/original/qk3eQ8jW4opJ48gFWYUXWaMT4l.jpg\",\n      },\n      {\n        \"type\": \"background\",\n        \"url\": \"https://image.tmdb.org/t/p/original/3uE9SUywNbj1qSAuYCGgbTTYku5.jpg\",\n      },\n      {\n        \"type\": \"clearLogo\",\n        \"url\": \"https://image.tmdb.org/t/p/original/rIi0lY2UftYuKDJ4OlIefDdijve.png\",\n      }\n    ]\n  }\n}\n```\n\n### Children and Grandchildren Requests\n\nFor items which contain child items, like TV Shows and Seasons, these types should also respond to requests for `/children` and `/grandchildren`, e.g. `/library/metadata/tmdb-show-123/children`.\n\nFor TV Shows and Seasons this should return a [MediaContainer](#mediacontainer) object with an array of [Metadata Objects](#metadata-object) for their Seasons and Episodes respectively.\n\nIt is required that these two endpoints support paged requests via the `X-Plex-Container-Size` and `X-Plex-Container-Start` headers/params.\n\n### Match Feature\n\nThis is a path to retrieve potential matches to metadata items based on contextual hints passed in your request body. This should return a [MediaContainer Object](#mediacontainer) possibly containing multiple Metadata objects (by default should only return the best result only).\n\nIt is called by making a `POST` request to the path defined by the `Match` feature inside the root of your provider.\n\nThis may be where it is useful supporting [Response Customization](#response-customization-optional) as match responses don't always need to contain the full Metadata object responses.\n\nA request body is requ

# --- truncated at 32 KB (357 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/plex/refs/heads/main/openapi/plex-library-api-openapi.yml