@lukehagar/plexjs v0.39.0

@lukehagar/plexjs

Summary

Plex-API: An Open API Spec for interacting with Plex.tv and Plex Media Server

Plex Media Server OpenAPI Specification

An Open Source OpenAPI Specification for Plex Media Server

Automation and SDKs provided by Speakeasy

Documentation

API Documentation

SDKs

The following SDKs are generated from the OpenAPI Specification. They are automatically generated and may not be fully tested. If you find any issues, please open an issue on the main specification Repository.

Table of Contents

• @lukehagar/plexjs
• Plex Media Server OpenAPI Specification
  • Documentation
  • SDKs
  • SDK Installation
  • SDK Example Usage
  • Available Resources and Operations
  • Error Handling
  • Server Selection
  • Custom HTTP Client
  • Authentication
  • Requirements
  • Standalone functions
  • File uploads
  • Retries
  • Debugging
• Development
  • Maturity
  • Contributions

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @lukehagar/plexjs

PNPM

pnpm add @lukehagar/plexjs

Bun

bun add @lukehagar/plexjs

Yarn

yarn add @lukehagar/plexjs zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

SDK Example Usage

Example

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

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.server.getServerCapabilities();

  console.log(result);
}

run();

Available Resources and Operations

activities

• getServerActivities - Get Server Activities
• cancelServerActivities - Cancel Server Activities

authentication

• getTransientToken - Get a Transient Token
• getSourceConnectionInformation - Get Source Connection Information
• getTokenDetails - Get Token Details
• postUsersSignInData - Get User Sign In Data

butler

• getButlerTasks - Get Butler tasks
• startAllTasks - Start all Butler tasks
• stopAllTasks - Stop all Butler tasks
• startTask - Start a single Butler task
• stopTask - Stop a single Butler task

hubs

• getGlobalHubs - Get Global Hubs
• getRecentlyAdded - Get Recently Added
• getLibraryHubs - Get library specific hubs

library

• getFileHash - Get Hash Value
• getRecentlyAddedLibrary - Get Recently Added
• getAllLibraries - Get All Libraries
• getLibraryDetails - Get Library Details
• deleteLibrary - Delete Library Section
• getLibraryItems - Get Library Items
• getLibrarySectionsAll - Get Library section media by tag ALL
• getRefreshLibraryMetadata - Refresh Metadata Of The Library
• getSearchLibrary - Search Library
• getGenresLibrary - Get Genres of library media
• getCountriesLibrary - Get Countries of library media
• getActorsLibrary - Get Actors of library media
• getSearchAllLibraries - Search All Libraries
• getMediaMetaData - Get Media Metadata
• getMediaArts - Get Media Background Artwork
• postMediaArts - Upload Media Background Artwork
• getMediaPosters - Get Media Posters
• postMediaPoster - Upload Media Poster
• getMetadataChildren - Get Items Children
• getTopWatchedContent - Get Top Watched Content

log

• logLine - Logging a single line message.
• logMultiLine - Logging a multi-line message
• enablePaperTrail - Enabling Papertrail

media

• markPlayed - Mark Media Played
• markUnplayed - Mark Media Unplayed
• updatePlayProgress - Update Media Play Progress
• getBannerImage - Get Banner Image
• getThumbImage - Get Thumb Image

playlists

• createPlaylist - Create a Playlist
• getPlaylists - Get All Playlists
• getPlaylist - Retrieve Playlist
• deletePlaylist - Deletes a Playlist
• updatePlaylist - Update a Playlist
• getPlaylistContents - Retrieve Playlist Contents
• clearPlaylistContents - Delete Playlist Contents
• addPlaylistContents - Adding to a Playlist
• uploadPlaylist - Upload Playlist

plex

• getCompanionsData - Get Companions Data
• getUserFriends - Get list of friends of the user logged in
• getGeoData - Get Geo Data
• getHomeData - Get Plex Home Data
• getServerResources - Get Server Resources
• getPin - Get a Pin
• getTokenByPinId - Get Access Token by PinId

search

• performSearch - Perform a search
• performVoiceSearch - Perform a voice search
• getSearchResults - Get Search Results

server

• getServerCapabilities - Get Server Capabilities
• getServerPreferences - Get Server Preferences
• getAvailableClients - Get Available Clients
• getDevices - Get Devices
• getServerIdentity - Get Server Identity
• getMyPlexAccount - Get MyPlex Account
• getResizedPhoto - Get a Resized Photo
• getMediaProviders - Get Media Providers
• getServerList - Get Server List

sessions

• getSessions - Get Active Sessions
• getSessionHistory - Get Session History
• getTranscodeSessions - Get Transcode Sessions
• stopTranscodeSession - Stop a Transcode Session

statistics

• getStatistics - Get Media Statistics
• getResourcesStatistics - Get Resources Statistics
• getBandwidthStatistics - Get Bandwidth Statistics

updater

• getUpdateStatus - Querying status of updates
• checkForUpdates - Checking for updates
• applyUpdates - Apply Updates

users

• getUsers - Get list of all connected users

video

• getTimeline - Get the timeline for a media item
• startUniversalTranscode - Start Universal Transcode

watchlist

• getWatchList - Get User Watchlist

Error Handling

PlexAPIError is the base class for all HTTP error responses. It has the following properties:

Example

import { PlexAPI } from "@lukehagar/plexjs";
import * as errors from "@lukehagar/plexjs/sdk/models/errors";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  try {
    const result = await plexAPI.server.getServerCapabilities();

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.PlexAPIError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.GetServerCapabilitiesBadRequest) {
        console.log(error.data$.errors); // Errors[]
        console.log(error.data$.rawResponse); // Response
      }
    }
  }
}

run();

Error Classes

Primary error:

• PlexAPIError: The base class for HTTP error responses.

Network errors:

• ConnectionError: HTTP client was unable to make a request to a server.
• RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
• RequestAbortedError: HTTP request was aborted by the client.
• InvalidRequestError: Any input used to create a request is invalid.
• UnexpectedClientError: Unrecognised or unexpected error.

Inherit from PlexAPIError:

• GetServerCapabilitiesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetServerPreferencesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetAvailableClientsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetDevicesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetMyPlexAccountBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetResizedPhotoBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetMediaProvidersBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetServerListBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• MarkPlayedBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• MarkUnplayedBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• UpdatePlayProgressBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetBannerImageBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetThumbImageBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTimelineBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StartUniversalTranscodeBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetServerActivitiesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• CancelServerActivitiesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetButlerTasksBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StartAllTasksBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StopAllTasksBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StartTaskBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StopTaskBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetCompanionsDataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetUserFriendsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetGeoDataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetHomeDataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetServerResourcesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetPinBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTokenByPinIdBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetGlobalHubsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetLibraryHubsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• PerformSearchBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• PerformVoiceSearchBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSearchResultsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetFileHashBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetRecentlyAddedLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetAllLibrariesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetLibraryDetailsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• DeleteLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetLibraryItemsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetLibrarySectionsAllBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetRefreshLibraryMetadataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSearchLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetGenresLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetCountriesLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetActorsLibraryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSearchAllLibrariesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetMediaMetaDataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetMetadataChildrenBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTopWatchedContentBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetWatchListBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• LogLineBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• LogMultiLineBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• EnablePaperTrailBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• CreatePlaylistBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetPlaylistsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetPlaylistBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• DeletePlaylistBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• UpdatePlaylistBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetPlaylistContentsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• ClearPlaylistContentsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• AddPlaylistContentsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• UploadPlaylistBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTransientTokenBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSourceConnectionInformationBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTokenDetailsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• PostUsersSignInDataBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetStatisticsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetResourcesStatisticsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetBandwidthStatisticsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSessionsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetSessionHistoryBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetTranscodeSessionsBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• StopTranscodeSessionBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetUpdateStatusBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• CheckForUpdatesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• ApplyUpdatesBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetUsersBadRequest: Bad Request - A parameter was not specified, or was specified incorrectly. Status code 400. Applicable to 1 of 84 methods.*
• GetServerCapabilitiesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetServerPreferencesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetAvailableClientsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetDevicesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetMyPlexAccountUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetResizedPhotoUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetMediaProvidersUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetServerListUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• MarkPlayedUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• MarkUnplayedUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• UpdatePlayProgressUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetBannerImageUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetThumbImageUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTimelineUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StartUniversalTranscodeUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetServerActivitiesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• CancelServerActivitiesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetButlerTasksUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StartAllTasksUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StopAllTasksUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StartTaskUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StopTaskUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetCompanionsDataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetUserFriendsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetGeoDataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetHomeDataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetServerResourcesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetGlobalHubsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetLibraryHubsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• PerformSearchUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• PerformVoiceSearchUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSearchResultsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetFileHashUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetRecentlyAddedLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetAllLibrariesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetLibraryDetailsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• DeleteLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetLibraryItemsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetLibrarySectionsAllUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetRefreshLibraryMetadataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSearchLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetGenresLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetCountriesLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetActorsLibraryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSearchAllLibrariesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetMediaMetaDataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetMetadataChildrenUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTopWatchedContentUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetWatchListUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• LogLineUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• LogMultiLineUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• EnablePaperTrailUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• CreatePlaylistUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetPlaylistsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetPlaylistUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• DeletePlaylistUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• UpdatePlaylistUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetPlaylistContentsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• ClearPlaylistContentsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• AddPlaylistContentsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• UploadPlaylistUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTransientTokenUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSourceConnectionInformationUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTokenDetailsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• PostUsersSignInDataUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetStatisticsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetResourcesStatisticsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetBandwidthStatisticsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSessionsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetSessionHistoryUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTranscodeSessionsUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• StopTranscodeSessionUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetUpdateStatusUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• CheckForUpdatesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• ApplyUpdatesUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetUsersUnauthorized: Unauthorized - Returned if the X-Plex-Token is missing from the header or query. Status code 401. Applicable to 1 of 84 methods.*
• GetTokenByPinIdResponseBody: Not Found or Expired. Status code 404. Applicable to 1 of 84 methods.*
• GetServerIdentityRequestTimeout: Request Timeout. Status code 408. Applicable to 1 of 84 methods.*
• ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.

* Check the method documentation to see if the error is applicable.

Server Selection

Server Variables

The default server {protocol}://{ip}:{port} contains variables and is set to https://10.10.10.47:32400 by default. To override default values, the following parameters are available when initializing the SDK client instance:

Example

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

const plexAPI = new PlexAPI({
  protocol: "https",
  ip: "4982:bc2a:b4f8:efb5:2394:5bc3:ab4f:0e6d",
  port: "44765",
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.server.getServerCapabilities();

  console.log(result);
}

run();

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

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

const plexAPI = new PlexAPI({
  serverURL: "https://10.10.10.47:32400",
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.server.getServerCapabilities();

  console.log(result);
}

run();

Override Server URL Per-Operation

The server URL can also be overridden on a per-operation basis, provided a server list was specified for the operation. For example:

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

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.plex.getCompanionsData({
    serverURL: "https://plex.tv/api/v2",
  });

  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { PlexAPI } from "@lukehagar/plexjs";
import { HTTPClient } from "@lukehagar/plexjs/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new PlexAPI({ httpClient });

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

To authenticate with the API the accessToken parameter must be set when initializing the SDK client instance. For example:

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

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
});

async function run() {
  const result = await plexAPI.server.getServerCapabilities();

  console.log(result);
}

run();

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

• activitiesCancelServerActivities - Cancel Server Activities
• activitiesGetServerActivities - Get Server Activities
• authenticationGetSourceConnectionInformation - Get Source Connection Information
• authenticationGetTokenDetails - Get Token Details
• authenticationGetTransientToken - Get a Transient Token
• authenticationPostUsersSignInData - Get User Sign In Data
• butlerGetButlerTasks - Get Butler tasks
• butlerStartAllTasks - Start all Butler tasks
• butlerStartTask - Start a single Butler task
• butlerStopAllTasks - Stop all Butler tasks
• butlerStopTask - Stop a single Butler task
• hubsGetGlobalHubs - Get Global Hubs
• hubsGetLibraryHubs - Get library specific hubs
• hubsGetRecentlyAdded - Get Recently Added
• libraryDeleteLibrary - Delete Library Section
• libraryGetActorsLibrary - Get Actors of library media
• libraryGetAllLibraries - Get All Libraries
• libraryGetCountriesLibrary - Get Countries of library media
• libraryGetFileHash - Get Hash Value
• libraryGetGenresLibrary - Get Genres of library media
• libraryGetLibraryDetails - Get Library Details
• libraryGetLibraryItems - Get Library Items
• libraryGetLibrarySectionsAll - Get Library section media by tag ALL
• libraryGetMediaArts - Get Media Background Artwork
• libraryGetMediaMetaData - Get Media Metadata
• libraryGetMediaPosters - Get Media Posters
• libraryGetMetadataChildren - Get Items Children
• libraryGetRecentlyAddedLibrary - Get Recently Added
• libraryGetRefreshLibraryMetadata - Refresh Metadata Of The Library
• libraryGetSearchAllLibraries - Search All Libraries
• libraryGetSearchLibrary - Search Library
• libraryGetTopWatchedContent - Get Top Watched Content
• libraryPostMediaArts - Upload Media Background Artwork
• libraryPostMediaPoster - Upload Media Poster
• logEnablePaperTrail - Enabling Papertrail
• logLogLine - Logging a single line message.
• logLogMultiLine - Logging a multi-line message
• mediaGetBannerImage - Get Banner Image
• mediaGetThumbImage - Get Thumb Image
• mediaMarkPlayed - Mark Media Played
• mediaMarkUnplayed - Mark Media Unplayed
• mediaUpdatePlayProgress - Update Media Play Progress
• playlistsAddPlaylistContents - Adding to a Playlist
• playlistsClearPlaylistContents - Delete Playlist Contents
• playlistsCreatePlaylist - Create a Playlist
• playlistsDeletePlaylist - Deletes a Playlist
• playlistsGetPlaylist - Retrieve Playlist
• playlistsGetPlaylistContents - Retrieve Playlist Contents
• playlistsGetPlaylists - Get All Playlists
• playlistsUpdatePlaylist - Update a Playlist
• playlistsUploadPlaylist - Upload Playlist
• plexGetCompanionsData - Get Companions Data
• plexGetGeoData - Get Geo Data
• plexGetHomeData - Get Plex Home Data
• plexGetPin - Get a Pin
• plexGetServerResources - Get Server Resources
• plexGetTokenByPinId - Get Access Token by PinId
• plexGetUserFriends - Get list of friends of the user logged in
• searchGetSearchResults - Get Search Results
• searchPerformSearch - Perform a search
• searchPerformVoiceSearch - Perform a voice search
• serverGetAvailableClients - Get Available Clients
• serverGetDevices - Get Devices
• serverGetMediaProviders - Get Media Providers
• serverGetMyPlexAccount - Get MyPlex Account
• serverGetResizedPhoto - Get a Resized Photo
• serverGetServerCapabilities - Get Server Capabilities
• serverGetServerIdentity - Get Server Identity
• serverGetServerList - Get Server List
• serverGetServerPreferences - Get Server Preferences
• sessionsGetSessionHistory - Get Session History
• sessionsGetSessions - Get Active Sessions
• sessionsGetTranscodeSessions - Get Transcode Sessions
• sessionsStopTranscodeSession - Stop a Transcode Session
• statisticsGetBandwidthStatistics - Get Bandwidth Statistics
• statisticsGetResourcesStatistics - Get Resources Statistics
• statisticsGetStatistics - Get Media Statistics
• updaterApplyUpdates - Apply Updates
• updaterCheckForUpdates - Checking for updates
• updaterGetUpdateStatus - Querying status of updates
• usersGetUsers - Get list of all connected users
• videoGetTimeline - Get the timeline for a media item
• videoStartUniversalTranscode - Start Universal Transcode
• watchlistGetWatchList - Get User Watchlist

File uploads

Certain SDK methods accept files as part of a multi-part request. It is possible and typically recommended to upload files as a stream rather than reading the entire contents into memory. This avoids excessive memory consumption and potentially crashing with out-of-memory errors when working with very large files. The following example demonstrates how to attach a file stream to a request.

!TIP

Depe