plexcsharp/docs/sdks/library/README.md

Library

(Library)

Overview

API Calls interacting with Plex Media Server Libraries

Available Operations

• GetFileHash - Get Hash Value
• GetRecentlyAdded - Get Recently Added
• GetLibraries - Get All Libraries
• GetLibrary - Get Library Details
• DeleteLibrary - Delete Library Section
• GetLibraryItems - Get Library Items
• RefreshLibrary - Refresh Library
• SearchLibrary - Search Library
• GetMetadata - Get Items Metadata
• GetMetadataChildren - Get Items Children
• GetOnDeck - Get On Deck

GetFileHash

This resource returns hash values for local files

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

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	✔️	This is the path to the local file, must be prefixed by file://	file://C:\Image.png&type=13
Type	double	➖	Item type

Response

GetFileHashResponse

GetRecentlyAdded

This endpoint will return the recently added content.

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetRecentlyAddedAsync();

// handle response

Response

GetRecentlyAddedResponse

GetLibraries

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

using PlexAPI;
using PlexAPI.Models.Components;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetLibrariesAsync();

// handle response

Response

GetLibrariesResponse

GetLibrary

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

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetLibraryAsync(
    sectionId: 1000D,
    includeDetails: IncludeDetails.Zero);

// handle response

Parameters

Parameter	Type	Required	Description	Example
SectionId	double	✔️	the Id of the library to query	1000
IncludeDetails	IncludeDetails	➖	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

GetLibraryResponse

DeleteLibrary

Delate a library using a specific section

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.DeleteLibraryAsync(sectionId: 1000D);

// handle response

Parameters

Parameter	Type	Required	Description	Example
SectionId	double	✔️	the Id of the library to query	1000

Response

DeleteLibraryResponse

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

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetLibraryItemsAsync(
    sectionId: 451092,
    tag: Tag.Unwatched);

// handle response

Parameters

Parameter	Type	Required	Description
SectionId	long	✔️	the Id of the library to query
Tag	Tag	✔️	A key representing a specific tag within the section.

Response

GetLibraryItemsResponse

RefreshLibrary

This endpoint Refreshes the library.

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.RefreshLibraryAsync(sectionId: 934.16D);

// handle response

Parameters

Parameter	Type	Required	Description
SectionId	double	✔️	the Id of the library to refresh

Response

RefreshLibraryResponse

SearchLibrary

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

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.SearchLibraryAsync(
    sectionId: 933505,
    type: Type.Four);

// handle response

Parameters

Parameter	Type	Required	Description
SectionId	long	✔️	the Id of the library to query
Type	Type	✔️	Plex content type to search for

Response

SearchLibraryResponse

GetMetadata

This endpoint will return the metadata of a library item specified with the ratingKey.

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetMetadataAsync(ratingKey: 8382.31D);

// handle response

Parameters

Parameter	Type	Required	Description
RatingKey	double	✔️	the id of the library item to return the children of.

Response

GetMetadataResponse

GetMetadataChildren

This endpoint will return the children of of a library item specified with the ratingKey.

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;
using PlexAPI.Models.Requests;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetMetadataChildrenAsync(ratingKey: 1539.14D);

// handle response

Parameters

Parameter	Type	Required	Description
RatingKey	double	✔️	the id of the library item to return the children of.

Response

GetMetadataChildrenResponse

GetOnDeck

This endpoint will return the on deck content.

Example Usage

using PlexAPI;
using PlexAPI.Models.Components;

var sdk = new PlexAPISDK(AccessToken: "<YOUR_API_KEY_HERE>");

var res = await sdk.Library.GetOnDeckAsync();

// handle response

Response

GetOnDeckResponse