LukeParke/plexpy
1
0
Fork 0
mirror of https://github.com/LukeHagar/plexpy.git synced 2025-12-06 12:47:44 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
cf7a46a06492f2aa0b859997fe40e546f583a9f3
plexpy/docs/sdks/library
History

README.md

Library

(library)

Overview

API Calls interacting with Plex Media Server Libraries

Available Operations

get_file_hash

This resource returns hash values for local files

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

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

    assert res is not None

    # Handle response
    print(res)

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 Type Status Code Content Type
errors.GetFileHashBadRequest 400 application/json
errors.GetFileHashUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_recently_added_library

This endpoint will return the recently added content.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_recently_added_library(request={
        "content_directory_id": 2,
        "pinned_content_directory_id": [
            3,
            5,
            7,
            13,
            12,
            1,
            6,
            14,
            2,
            10,
            16,
            17,
        ],
        "section_id": 2,
        "type": operations.QueryParamType.TV_SHOW,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetRecentlyAddedLibraryResponse

Errors

Error Type Status Code Content Type
errors.GetRecentlyAddedLibraryBadRequest 400 application/json
errors.GetRecentlyAddedLibraryUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_all_libraries()

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetAllLibrariesResponse

Errors

Error Type Status Code Content Type
errors.GetAllLibrariesBadRequest 400 application/json
errors.GetAllLibrariesUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

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

    assert res.object is not None

    # Handle response
    print(res.object)

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 Type Status Code Content Type
errors.GetLibraryDetailsBadRequest 400 application/json
errors.GetLibraryDetailsUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

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

    assert res is not None

    # Handle response
    print(res)

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 Type Status Code Content Type
errors.DeleteLibraryBadRequest 400 application/json
errors.DeleteLibraryUnauthorized 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.
  • albums: Items categorized by album.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_library_items(request={
        "tag": operations.Tag.EDITION,
        "type": operations.GetLibraryItemsQueryParamType.TV_SHOW,
        "section_key": 9518,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

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 Type Status Code Content Type
errors.GetLibraryItemsBadRequest 400 application/json
errors.GetLibraryItemsUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_all_media_library

Retrieves a list of all general media data for this library.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_all_media_library(request={
        "section_key": 9518,
        "type": operations.GetAllMediaLibraryQueryParamType.TV_SHOW,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetAllMediaLibraryResponse

Errors

Error Type Status Code Content Type
errors.GetAllMediaLibraryBadRequest 400 application/json
errors.GetAllMediaLibraryUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

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

    assert res is not None

    # Handle response
    print(res)

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 Type Status Code Content Type
errors.GetRefreshLibraryMetadataBadRequest 400 application/json
errors.GetRefreshLibraryMetadataUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_search_library(section_key=9518, type_=operations.GetSearchLibraryQueryParamType.TV_SHOW)

    assert res.object is not None

    # Handle response
    print(res.object)

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.GetSearchLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
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 Type Status Code Content Type
errors.GetSearchLibraryBadRequest 400 application/json
errors.GetSearchLibraryUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_genres_library

Retrieves a list of all the genres that are found for the media in this library.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_genres_library(section_key=9518, type_=operations.GetGenresLibraryQueryParamType.TV_SHOW)

    assert res.object is not None

    # Handle response
    print(res.object)

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.GetGenresLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
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.GetGenresLibraryResponse

Errors

Error Type Status Code Content Type
errors.GetGenresLibraryBadRequest 400 application/json
errors.GetGenresLibraryUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_countries_library

Retrieves a list of all the countries that are found for the media in this library.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_countries_library(section_key=9518, type_=operations.GetCountriesLibraryQueryParamType.TV_SHOW)

    assert res.object is not None

    # Handle response
    print(res.object)

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.GetCountriesLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
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.GetCountriesLibraryResponse

Errors

Error Type Status Code Content Type
errors.GetCountriesLibraryBadRequest 400 application/json
errors.GetCountriesLibraryUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_actors_library

Retrieves a list of all the actors that are found for the media in this library.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_actors_library(section_key=9518, type_=operations.GetActorsLibraryQueryParamType.TV_SHOW)

    assert res.object is not None

    # Handle response
    print(res.object)

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.GetActorsLibraryQueryParamType ✔️ The type of media to retrieve or filter by.
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.GetActorsLibraryResponse

Errors

Error Type Status Code Content Type
errors.GetActorsLibraryBadRequest 400 application/json
errors.GetActorsLibraryUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_search_all_libraries

Search the provided query across all library sections, or a single section, and return matches as hubs, split up by type.

Example Usage

from plex_api_client import PlexAPI
from plex_api_client.models import operations


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_search_all_libraries(request={
        "query": "<value>",
        "client_id": "3381b62b-9ab7-4e37-827b-203e9809eb58",
        "search_types": [
            operations.SearchTypes.PEOPLE,
        ],
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetSearchAllLibrariesResponse

Errors

Error Type Status Code Content Type
errors.GetSearchAllLibrariesBadRequest 400 application/json
errors.GetSearchAllLibrariesUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_media_meta_data

This endpoint will return all the (meta)data of a library item specified with by the ratingKey.

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_media_meta_data(request={
        "rating_key": 9518,
        "include_concerts": True,
        "include_extras": True,
        "include_on_deck": True,
        "include_popular_leaves": True,
        "include_preferences": True,
        "include_reviews": True,
        "include_chapters": True,
        "include_stations": True,
        "include_external_media": True,
        "async_augment_metadata": True,
        "async_check_files": True,
        "async_refresh_analysis": True,
        "async_refresh_local_media_agent": True,
    })

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetMediaMetaDataResponse

Errors

Error Type Status Code Content Type
errors.GetMediaMetaDataBadRequest 400 application/json
errors.GetMediaMetaDataUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*

get_media_arts

Returns the background artwork for a library item.

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_media_arts(rating_key=16099)

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetMediaArtsResponse

Errors

Error Type Status Code Content Type
errors.SDKError 4XX, 5XX */*

post_media_arts

Uploads an image to use as the background artwork for a library item, either from a local file or a remote URL

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.post_media_arts(rating_key=2268, url="https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b")

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
rating_key int ✔️ the id of the library item to return the posters of. 2268
url Optional[str] ➖ The URL of the image, if uploading a remote image https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
request_body Optional[Union[bytes, IO[bytes], io.BufferedReader]] ➖ The contents of the image, if uploading a local file
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

operations.PostMediaArtsResponse

Errors

Error Type Status Code Content Type
errors.SDKError 4XX, 5XX */*

get_media_posters

Returns the available posters for a library item.

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_media_posters(rating_key=16099)

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

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

Response

operations.GetMediaPostersResponse

Errors

Error Type Status Code Content Type
errors.SDKError 4XX, 5XX */*

post_media_poster

Uploads a poster to a library item, either from a local file or a remote URL

Example Usage

from plex_api_client import PlexAPI


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.post_media_poster(rating_key=2268, url="https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b")

    assert res is not None

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
rating_key int ✔️ the id of the library item to return the posters of. 2268
url Optional[str] ➖ The URL of the image, if uploading a remote image https://api.mediux.pro/assets/fcfdc487-dd07-4993-a0c1-0a3015362e5b
request_body Optional[Union[bytes, IO[bytes], io.BufferedReader]] ➖ The contents of the image, if uploading a local file
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

operations.PostMediaPosterResponse

Errors

Error Type Status Code Content Type
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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

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

    assert res.object is not None

    # Handle response
    print(res.object)

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 Type Status Code Content Type
errors.GetMetadataChildrenBadRequest 400 application/json
errors.GetMetadataChildrenUnauthorized 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


with PlexAPI(
    access_token="<YOUR_API_KEY_HERE>",
) as plex_api:

    res = plex_api.library.get_top_watched_content(type_=operations.GetTopWatchedContentQueryParamType.TV_SHOW, include_guids=1)

    assert res.object is not None

    # Handle response
    print(res.object)

Parameters

Parameter Type Required Description Example
type operations.GetTopWatchedContentQueryParamType ✔️ The type of media to retrieve or filter by.
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 Type Status Code Content Type
errors.GetTopWatchedContentBadRequest 400 application/json
errors.GetTopWatchedContentUnauthorized 401 application/json
errors.SDKError 4XX, 5XX */*