Files
plexjava/docs/sdks/library

Library

(library())

Overview

API Calls interacting with Plex Media Server Libraries

Available Operations

getFileHash

This resource returns hash values for local files

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetFileHashResponse res = sdk.library().getFileHash()
                .url("file://C:\Image.png&type=13")
                .type(4462.17d)
                .call();

            // handle response
        } catch (lukehagar.plexapi.plexapi.models.errors.GetFileHashResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

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 Optional<? extends Double> Item type

Response

lukehagar.plexapi.plexapi.models.operations.GetFileHashResponse

Errors

Error Object Status Code Content Type
models/errors/GetFileHashResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

getRecentlyAdded

This endpoint will return the recently added content.

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetRecentlyAddedResponse res = sdk.library().getRecentlyAdded()
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetRecentlyAddedResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

lukehagar.plexapi.plexapi.models.operations.GetRecentlyAddedResponse

Errors

Error Object Status Code Content Type
models/errors/GetRecentlyAddedResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

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

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetLibrariesResponse res = sdk.library().getLibraries()
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetLibrariesResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

lukehagar.plexapi.plexapi.models.operations.GetLibrariesResponse

Errors

Error Object Status Code Content Type
models/errors/GetLibrariesResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

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

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetLibraryResponse res = sdk.library().getLibrary()
                .sectionId(1000d)
                .includeDetails(IncludeDetails.ZERO)
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetLibraryResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter Type Required Description Example
sectionId double ✔️ the Id of the library to query 1000
includeDetails Optional<? extends lukehagar.plexapi.plexapi.models.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.

Response

lukehagar.plexapi.plexapi.models.operations.GetLibraryResponse

Errors

Error Object Status Code Content Type
models/errors/GetLibraryResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

deleteLibrary

Delate a library using a specific section

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            DeleteLibraryResponse res = sdk.library().deleteLibrary()
                .sectionId(1000d)
                .call();

            // handle response
        } catch (lukehagar.plexapi.plexapi.models.errors.DeleteLibraryResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

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

Response

lukehagar.plexapi.plexapi.models.operations.DeleteLibraryResponse

Errors

Error Object Status Code Content Type
models/errors/DeleteLibraryResponseBody 401 application/json
models/errors/SDKError 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

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetLibraryItemsResponse res = sdk.library().getLibraryItems()
                .sectionId("<value>")
                .tag(Tag.GENRE)
                .includeGuids(1L)
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetLibraryItemsResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter Type Required Description Example
sectionId java.lang.Object ✔️ the Id of the library to query
tag lukehagar.plexapi.plexapi.models.operations.Tag ✔️ A key representing a specific tag within the section.
includeGuids Optional<? extends Long> Adds the Guids object to the response
1

Response

lukehagar.plexapi.plexapi.models.operations.GetLibraryItemsResponse

Errors

Error Object Status Code Content Type
models/errors/GetLibraryItemsResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

refreshLibrary

This endpoint Refreshes the library.

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            RefreshLibraryResponse res = sdk.library().refreshLibrary()
                .sectionId(934.16d)
                .call();

            // handle response
        } catch (lukehagar.plexapi.plexapi.models.errors.RefreshLibraryResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

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

Response

lukehagar.plexapi.plexapi.models.operations.RefreshLibraryResponse

Errors

Error Object Status Code Content Type
models/errors/RefreshLibraryResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

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

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            SearchLibraryResponse res = sdk.library().searchLibrary()
                .sectionId(933505L)
                .type(Type.FOUR)
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.SearchLibraryResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter Type Required Description
sectionId long ✔️ the Id of the library to query
type lukehagar.plexapi.plexapi.models.operations.Type ✔️ Plex content type to search for

Response

lukehagar.plexapi.plexapi.models.operations.SearchLibraryResponse

Errors

Error Object Status Code Content Type
models/errors/SearchLibraryResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

getMetadata

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

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetMetadataResponse res = sdk.library().getMetadata()
                .ratingKey(8382.31d)
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetMetadataResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

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

Response

lukehagar.plexapi.plexapi.models.operations.GetMetadataResponse

Errors

Error Object Status Code Content Type
models/errors/GetMetadataResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

getMetadataChildren

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

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetMetadataChildrenResponse res = sdk.library().getMetadataChildren()
                .ratingKey(1539.14d)
                .includeElements("<value>")
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetMetadataChildrenResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter Type Required Description
ratingKey double ✔️ the id of the library item to return the children of.
includeElements Optional<? extends String> Adds additional elements to the response. Supported types are (Stream)

Response

lukehagar.plexapi.plexapi.models.operations.GetMetadataChildrenResponse

Errors

Error Object Status Code Content Type
models/errors/GetMetadataChildrenResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*

getTopWatchedContent

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

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetTopWatchedContentResponse res = sdk.library().getTopWatchedContent()
                .type(505531L)
                .includeGuids(1L)
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter Type Required Description Example
type long ✔️ the library type (1 - movies, 2 - shows, 3 - music)
includeGuids Optional<? extends Long> Adds the Guids object to the response
1

Response

lukehagar.plexapi.plexapi.models.operations.GetTopWatchedContentResponse

Errors

Error Object Status Code Content Type
models/errors/SDKError 4xx-5xx */*

getOnDeck

This endpoint will return the on deck content.

Example Usage

package hello.world;

import java.math.BigDecimal;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.Optional;
import lukehagar.plexapi.plexapi.PlexAPI;
import lukehagar.plexapi.plexapi.models.operations.*;
import lukehagar.plexapi.plexapi.models.shared.*;
import lukehagar.plexapi.plexapi.models.shared.Security;
import lukehagar.plexapi.plexapi.utils.EventStream;
import org.openapitools.jackson.nullable.JsonNullable;
import static java.util.Map.entry;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("Postman")
                .build();

            GetOnDeckResponse res = sdk.library().getOnDeck()
                .call();

            if (res.object().isPresent()) {
                // handle response
            }
        } catch (lukehagar.plexapi.plexapi.models.errors.GetOnDeckResponseBody e) {
            // handle exception
            throw e;
        } catch (lukehagar.plexapi.plexapi.models.errors.SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Response

lukehagar.plexapi.plexapi.models.operations.GetOnDeckResponse

Errors

Error Object Status Code Content Type
models/errors/GetOnDeckResponseBody 401 application/json
models/errors/SDKError 4xx-5xx */*