# Library (*Library*) ## Overview API Calls interacting with Plex Media Server Libraries ### Available Operations * [GetFileHash](#getfilehash) - Get Hash Value * [GetRecentlyAdded](#getrecentlyadded) - Get Recently Added * [GetAllLibraries](#getalllibraries) - Get All Libraries * [GetLibraryDetails](#getlibrarydetails) - Get Library Details * [DeleteLibrary](#deletelibrary) - Delete Library Section * [GetLibraryItems](#getlibraryitems) - Get Library Items * [GetRefreshLibraryMetadata](#getrefreshlibrarymetadata) - Refresh Metadata Of The Library * [GetSearchLibrary](#getsearchlibrary) - Search Library * [GetMetaDataByRatingKey](#getmetadatabyratingkey) - Get Metadata by RatingKey * [GetMetadataChildren](#getmetadatachildren) - Get Items Children * [GetTopWatchedContent](#gettopwatchedcontent) - Get Top Watched Content * [GetOnDeck](#getondeck) - Get On Deck ## GetFileHash This resource returns hash values for local files ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetFileHashAsync( url: "file://C:\Image.png&type=13", type: 4462.17D ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | `Url` | *string* | :heavy_check_mark: | This is the path to the local file, must be prefixed by `file://` | file://C:\Image.png&type=13 | | `Type` | *double* | :heavy_minus_sign: | Item type | | ### Response **[GetFileHashResponse](../../Models/Requests/GetFileHashResponse.md)** ### Errors | Error Object | Status Code | Content Type | | --------------------------------------------- | --------------------------------------------- | --------------------------------------------- | | PlexAPI.Models.Errors.GetFileHashResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetRecentlyAdded This endpoint will return the recently added content. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetRecentlyAddedAsync( xPlexContainerStart: 0, xPlexContainerSize: 50 ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `XPlexContainerStart` | *int* | :heavy_minus_sign: | 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
| 0 | | `XPlexContainerSize` | *int* | :heavy_minus_sign: | 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
| 50 | ### Response **[GetRecentlyAddedResponse](../../Models/Requests/GetRecentlyAddedResponse.md)** ### Errors | Error Object | Status Code | Content Type | | -------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- | | PlexAPI.Models.Errors.GetRecentlyAddedResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetAllLibraries 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). ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetAllLibrariesAsync(); // handle response ``` ### Response **[GetAllLibrariesResponse](../../Models/Requests/GetAllLibrariesResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | | PlexAPI.Models.Errors.GetAllLibrariesResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetLibraryDetails ## 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. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetLibraryDetailsAsync( sectionKey: 9518, includeDetails: PlexAPI.Models.Requests.IncludeDetails.Zero ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SectionKey` | *int* | :heavy_check_mark: | The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
| 9518 | | `IncludeDetails` | [IncludeDetails](../../Models/Requests/IncludeDetails.md) | :heavy_minus_sign: | 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.
| | ### Response **[GetLibraryDetailsResponse](../../Models/Requests/GetLibraryDetailsResponse.md)** ### Errors | Error Object | Status Code | Content Type | | --------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | | PlexAPI.Models.Errors.GetLibraryDetailsResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## DeleteLibrary Delete a library using a specific section id ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.DeleteLibraryAsync(sectionKey: 9518); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `SectionKey` | *int* | :heavy_check_mark: | The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
| 9518 | ### Response **[DeleteLibraryResponse](../../Models/Requests/DeleteLibraryResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ----------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- | | PlexAPI.Models.Errors.DeleteLibraryResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetLibraryItems 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. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); GetLibraryItemsRequest req = new GetLibraryItemsRequest() { SectionKey = 9518, Tag = PlexAPI.Models.Requests.Tag.Edition, Type = PlexAPI.Models.Requests.Type.Two, IncludeGuids = PlexAPI.Models.Requests.IncludeGuids.One, IncludeMeta = PlexAPI.Models.Requests.IncludeMeta.One, XPlexContainerStart = 0, XPlexContainerSize = 50, }; var res = await sdk.Library.GetLibraryItemsAsync(req); // handle response ``` ### Parameters | Parameter | Type | Required | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `request` | [GetLibraryItemsRequest](../../Models/Requests/GetLibraryItemsRequest.md) | :heavy_check_mark: | The request object to use for the request. | ### Response **[GetLibraryItemsResponse](../../Models/Requests/GetLibraryItemsResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | | PlexAPI.Models.Errors.GetLibraryItemsResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetRefreshLibraryMetadata This endpoint Refreshes all the Metadata of the library. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetRefreshLibraryMetadataAsync( sectionKey: 9518, force: PlexAPI.Models.Requests.Force.One ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `SectionKey` | *int* | :heavy_check_mark: | The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
| 9518 | | `Force` | [Force](../../Models/Requests/Force.md) | :heavy_minus_sign: | Force the refresh even if the library is already being refreshed. | 0 | ### Response **[GetRefreshLibraryMetadataResponse](../../Models/Requests/GetRefreshLibraryMetadataResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ----------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | | PlexAPI.Models.Errors.GetRefreshLibraryMetadataResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetSearchLibrary 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. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetSearchLibraryAsync( sectionKey: 9518, type: PlexAPI.Models.Requests.QueryParamType.Two ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SectionKey` | *int* | :heavy_check_mark: | The unique key of the Plex library.
Note: This is unique in the context of the Plex server.
| 9518 | | `Type` | [QueryParamType](../../Models/Requests/QueryParamType.md) | :heavy_check_mark: | 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
| 2 | ### Response **[GetSearchLibraryResponse](../../Models/Requests/GetSearchLibraryResponse.md)** ### Errors | Error Object | Status Code | Content Type | | -------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- | | PlexAPI.Models.Errors.GetSearchLibraryResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetMetaDataByRatingKey This endpoint will return the metadata of a library item specified with the ratingKey. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetMetaDataByRatingKeyAsync(ratingKey: 9518); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | | `RatingKey` | *long* | :heavy_check_mark: | the id of the library item to return the children of. | 9518 | ### Response **[GetMetaDataByRatingKeyResponse](../../Models/Requests/GetMetaDataByRatingKeyResponse.md)** ### Errors | Error Object | Status Code | Content Type | | -------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | | PlexAPI.Models.Errors.GetMetaDataByRatingKeyResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetMetadataChildren This endpoint will return the children of of a library item specified with the ratingKey. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetMetadataChildrenAsync( ratingKey: 1539.14D, includeElements: "" ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `RatingKey` | *double* | :heavy_check_mark: | the id of the library item to return the children of. | | `IncludeElements` | *string* | :heavy_minus_sign: | Adds additional elements to the response. Supported types are (Stream)
| ### Response **[GetMetadataChildrenResponse](../../Models/Requests/GetMetadataChildrenResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ----------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------- | | PlexAPI.Models.Errors.GetMetadataChildrenResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetTopWatchedContent This endpoint will return the top watched content from libraries of a certain type ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Requests; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetTopWatchedContentAsync( type: PlexAPI.Models.Requests.GetTopWatchedContentQueryParamType.Two, includeGuids: 1 ); // handle response ``` ### Parameters | Parameter | Type | Required | Description | Example | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Type` | [GetTopWatchedContentQueryParamType](../../Models/Requests/GetTopWatchedContentQueryParamType.md) | :heavy_check_mark: | 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
| 2 | | `IncludeGuids` | *long* | :heavy_minus_sign: | Adds the Guids object to the response
| 1 | ### Response **[GetTopWatchedContentResponse](../../Models/Requests/GetTopWatchedContentResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | | PlexAPI.Models.Errors.GetTopWatchedContentResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* | ## GetOnDeck This endpoint will return the on deck content. ### Example Usage ```csharp using PlexAPI; using PlexAPI.Models.Components; var sdk = new PlexAPISDK( accessToken: "", xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40" ); var res = await sdk.Library.GetOnDeckAsync(); // handle response ``` ### Response **[GetOnDeckResponse](../../Models/Requests/GetOnDeckResponse.md)** ### Errors | Error Object | Status Code | Content Type | | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | | PlexAPI.Models.Errors.GetOnDeckResponseBody | 401 | application/json | | PlexAPI.Models.Errors.SDKException | 4xx-5xx | */* |