plexpy/docs/sdks/library/README.md

Library

(library)

Overview

API Calls interacting with Plex Media Server Libraries

Available Operations

• get_file_hash - Get Hash Value
• get_recently_added - Get Recently Added
• get_all_libraries - Get All Libraries
• get_library_details - Get Library Details
• delete_library - Delete Library Section
• get_library_items - Get Library Items
• get_refresh_library_metadata - Refresh Metadata Of The Library
• get_search_library - Search Library
• get_meta_data_by_rating_key - Get Metadata by RatingKey
• get_metadata_children - Get Items Children
• get_top_watched_content - Get Top Watched Content
• get_on_deck - Get On Deck

get_file_hash

This resource returns hash values for local files

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_file_hash(url="file://C:\Image.png&type=13")

if res is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
url	str	✔️	This is the path to the local file, must be prefixed by file://	file://C:\Image.png&type=13
type	Optional[float]	➖	Item type
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetFileHashResponse

Errors

Error Object	Status Code	Content Type
errors.GetFileHashResponseBody	400	application/json
errors.GetFileHashLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_recently_added

This endpoint will return the recently added content.

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_recently_added(x_plex_container_start=0, x_plex_container_size=50)

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
x_plex_container_start	Optional[int]	➖	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
x_plex_container_size	Optional[int]	➖	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
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetRecentlyAddedResponse

Errors

Error Object	Status Code	Content Type
errors.GetRecentlyAddedResponseBody	400	application/json
errors.GetRecentlyAddedLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_all_libraries

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

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_all_libraries()

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetAllLibrariesResponse

Errors

Error Object	Status Code	Content Type
errors.GetAllLibrariesResponseBody	400	application/json
errors.GetAllLibrariesLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_library_details

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

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_library_details(section_key=9518)

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
section_key	int	✔️	The unique key of the Plex library. Note: This is unique in the context of the Plex server.	9518
include_details	Optional[operations.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.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetLibraryDetailsResponse

Errors

Error Object	Status Code	Content Type
errors.GetLibraryDetailsResponseBody	400	application/json
errors.GetLibraryDetailsLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

delete_library

Delete a library using a specific section id

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.delete_library(section_key=9518)

if res is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
section_key	int	✔️	The unique key of the Plex library. Note: This is unique in the context of the Plex server.	9518
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.DeleteLibraryResponse

Errors

Error Object	Status Code	Content Type
errors.DeleteLibraryResponseBody	400	application/json
errors.DeleteLibraryLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_library_items

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

from plex_api_client import PlexAPI
from plex_api_client.models import operations

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_library_items(request={
    "section_key": 9518,
    "tag": operations.Tag.EDITION,
    "type": operations.Type.TWO,
    "include_guids": operations.IncludeGuids.ONE,
    "include_meta": operations.IncludeMeta.ONE,
    "x_plex_container_start": 0,
    "x_plex_container_size": 50,
})

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description
request	operations.GetLibraryItemsRequest	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetLibraryItemsResponse

Errors

Error Object	Status Code	Content Type
errors.GetLibraryItemsResponseBody	400	application/json
errors.GetLibraryItemsLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_refresh_library_metadata

This endpoint Refreshes all the Metadata of the library.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_refresh_library_metadata(section_key=9518, force=operations.Force.ONE)

if res is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
section_key	int	✔️	The unique key of the Plex library. Note: This is unique in the context of the Plex server.	9518
force	Optional[operations.Force]	➖	Force the refresh even if the library is already being refreshed.	0
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetRefreshLibraryMetadataResponse

Errors

Error Object	Status Code	Content Type
errors.GetRefreshLibraryMetadataResponseBody	400	application/json
errors.GetRefreshLibraryMetadataLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_search_library

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

from plex_api_client import PlexAPI
from plex_api_client.models import operations

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_search_library(section_key=9518, type_=operations.QueryParamType.TWO)

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
section_key	int	✔️	The unique key of the Plex library. Note: This is unique in the context of the Plex server.	9518
type	operations.QueryParamType	✔️	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
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetSearchLibraryResponse

Errors

Error Object	Status Code	Content Type
errors.GetSearchLibraryResponseBody	400	application/json
errors.GetSearchLibraryLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_meta_data_by_rating_key

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

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_meta_data_by_rating_key(rating_key=9518)

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
rating_key	int	✔️	the id of the library item to return the children of.	9518
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetMetaDataByRatingKeyResponse

Errors

Error Object	Status Code	Content Type
errors.GetMetaDataByRatingKeyResponseBody	400	application/json
errors.GetMetaDataByRatingKeyLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_metadata_children

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

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_metadata_children(rating_key=1539.14, include_elements="Stream")

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description
rating_key	float	✔️	the id of the library item to return the children of.
include_elements	Optional[str]	➖	Adds additional elements to the response. Supported types are (Stream)
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetMetadataChildrenResponse

Errors

Error Object	Status Code	Content Type
errors.GetMetadataChildrenResponseBody	400	application/json
errors.GetMetadataChildrenLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_top_watched_content

This endpoint will return the top watched content from libraries of a certain type

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_top_watched_content(type_=operations.GetTopWatchedContentQueryParamType.TWO, include_guids=1)

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description	Example
type	operations.GetTopWatchedContentQueryParamType	✔️	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
include_guids	Optional[int]	➖	Adds the Guids object to the response	1
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetTopWatchedContentResponse

Errors

Error Object	Status Code	Content Type
errors.GetTopWatchedContentResponseBody	400	application/json
errors.GetTopWatchedContentLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

get_on_deck

This endpoint will return the on deck content.

Example Usage

from plex_api_client import PlexAPI

s = PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
    x_plex_client_identifier="gcgzw5rz2xovp84b4vha3a40",
)

res = s.library.get_on_deck()

if res.object is not None:
    # handle response
    pass

Parameters

Parameter	Type	Required	Description
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.GetOnDeckResponse

Errors

Error Object	Status Code	Content Type
errors.GetOnDeckResponseBody	400	application/json
errors.GetOnDeckLibraryResponseBody	401	application/json
errors.SDKError	4xx-5xx	/