plexjs/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
• getMetadata - Get Items Metadata
• getMetadataChildren - Get Items Children
• getOnDeck - Get On Deck

getFileHash

This resource returns hash values for local files

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const url = "file://C:\Image.png&type=13";
  const type = 4462.17;
  
  const result = await sdk.library.getFileHash(url, type);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
url	string	✔️	This is the path to the local file, must be prefixed by file://	[object Object]
type	number	➖	Item type
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetFileHashResponse>

Errors

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

getRecentlyAdded

This endpoint will return the recently added content.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const result = await sdk.library.getRecentlyAdded();

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetRecentlyAddedResponse>

Errors

Error Object	Status Code	Content Type
errors.GetRecentlyAddedResponseBody	401	application/json
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

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const result = await sdk.library.getLibraries();

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetLibrariesResponse>

Errors

Error Object	Status Code	Content Type
errors.GetLibrariesResponseBody	401	application/json
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

import { PlexAPI } from "@lukehagar/plexjs";
import { IncludeDetails } from "@lukehagar/plexjs/models/operations";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const sectionId = 1000;
  const includeDetails = IncludeDetails.Zero;
  
  const result = await sdk.library.getLibrary(sectionId, includeDetails);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
sectionId	number	✔️	the Id of the library to query	[object Object]
includeDetails	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.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetLibraryResponse>

Errors

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

deleteLibrary

Delate a library using a specific section

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const sectionId = 1000;
  
  const result = await sdk.library.deleteLibrary(sectionId);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
sectionId	number	✔️	the Id of the library to query	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.DeleteLibraryResponse>

Errors

Error Object	Status Code	Content Type
errors.DeleteLibraryResponseBody	401	application/json
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.
• search?type=1: Search functionality within the section.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";
import { Tag } from "@lukehagar/plexjs/models/operations";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const sectionId = 451092;
  const tag = Tag.Unwatched;
  
  const result = await sdk.library.getLibraryItems(sectionId, tag);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
sectionId	number	✔️	the Id of the library to query
tag	operations.Tag	✔️	A key representing a specific tag within the section.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetLibraryItemsResponse>

Errors

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

refreshLibrary

This endpoint Refreshes the library.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const sectionId = 934.16;
  
  const result = await sdk.library.refreshLibrary(sectionId);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
sectionId	number	✔️	the Id of the library to refresh
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.RefreshLibraryResponse>

Errors

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

getMetadata

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

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const ratingKey = 8382.31;
  
  const result = await sdk.library.getMetadata(ratingKey);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
ratingKey	number	✔️	the id of the library item to return the children of.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetMetadataResponse>

Errors

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

getMetadataChildren

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

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const ratingKey = 1539.14;
  
  const result = await sdk.library.getMetadataChildren(ratingKey);

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
ratingKey	number	✔️	the id of the library item to return the children of.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetMetadataChildrenResponse>

Errors

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

getOnDeck

This endpoint will return the on deck content.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

async function run() {
  const sdk = new PlexAPI({
    accessToken: "<YOUR_API_KEY_HERE>",
  });

  const result = await sdk.library.getOnDeck();

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.

Response

Promise<operations.GetOnDeckResponse>

Errors

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