README.md

plex-api

Overview

Unofficial c# bindings for the Plex Media Server API. Our goal is to match all capabilities of the official Plex Web Client. A few of the many features we currently support are:

• Navigate local or remote shared libraries.
• Perform library actions such as scan, analyze, empty trash.
• Remote control and play media on connected clients.
• Listen in on all Plex Server notifications.

Installation & Documentation

From Powershell

    Nuget-Install 'Plex.Api'

Dotnet Cli

    dotnet add package 'Plex.Api'

Getting a PlexAccount Instance

NOTE: v2.0 documentation updates are incoming...

Boiler plate dependency injection setup.

    // Create Client Options
    var apiOptions = new ClientOptions
    {
        Product = "API_UnitTests",
        DeviceName = "API_UnitTests",
        ClientId = "MyClientId",
        Platform = "Web",
        Version = "v1"
    };

    // Setup Dependency Injection
    var services = new ServiceCollection();
    services.AddSingleton(apiOptions);
    services.AddTransient<IPlexServerClient, PlexServerClient>();
    services.AddTransient<IPlexAccountClient, PlexAccountClient>();
    services.AddTransient<IPlexLibraryClient, PlexLibraryClient>();
    services.AddTransient<IApiService, ApiService>();
    services.AddTransient<IPlexFactory, PlexFactory>();
    services.AddTransient<IPlexRequestsHttpClient, PlexRequestsHttpClient>();
    
    this.ServiceProvider = services.BuildServiceProvider();

The entry point to Plex-Api is with the PlexAccount class. You can instantiate a PlexAccount class using either your
Plex account login and password, or your Plex Auth Token.

    var plexFactory = this.ServiceProvider.GetService<IPlexFactory>();
    
    // Signin with Username, Password
    PlexAccount account = plexFactory
        .GetPlexAccount("username", "password");
    
    // or use and Plex Auth token
    PlexAccount account = plexFactory
        .GetPlexAccount("access_token_here");

PlexAccount Documentation

    // Get Announcements for Plex Account
    var announcements = account.Announcements().Result;
     
    // Get Server Summaries.  This does not return a Server Instance but a summary
    // of all servers tied to your Plex Account.  The servers may not be active/online.
    var servers = account.ServerSummaries().Result;
         
    // Get Servers (Active Servers w/Details)
    var servers = account.Servers().Result;
    
    // Get list of Friends for Plex Account
    var friends = account.Friends().Result;
    
    // Get Resources
    var resources = account.Resources().Result;
    
    // Get Providers
    var providers = account.Providers().Result;
    
    // Returns a list of all User objects connected to your account.
    // This includes both friends and pending invites. You can reference the user.Friend to
    // distinguish between the two.
    var users = account.users().Result;
    
    // Opt in or out of sharing stuff with plex.
    // See: https://www.plex.tv/about/privacy-legal/
    bool optOutOfPlaybackDetails = true;
    bool optOutOfLibraryDetails = true;
    account.OptOut(optOutOfPlaybackDetails, optOutOfLibraryDetails);
 
    // Get Account Devices
    var devices = account.Devices().Result;      

Server Documentation

    var servers = account.Servers().Result;
    var myServer = servers.Where(c=>c.Owned == "1").First();
    
    // Get Home OnDeck items
    var onDeckItems = myServer.HomeOnDeck().Result;
    
    // Get Recently Added items for the Home Hub
    var recentItems = myServer.HomeHubRecentlyAdded().Result;
    
    // Get Continue Watching items for the Home Hub
    var continueItems = myServer.HomeHubContinueWatching().Result;
    
    // Share library content with the specified user.
    string sections = "1,3,4";
    myServer.InviteFriend("testuser", sections); 
    
    // Get Providers for this Server
    var providers = myServer.Providers().Result;
    
    // Search Across All Hubs on this Server
    var items = myServer.HubLibrarySearch("Harry Potter").Result;
    
    // Get Play History for all library sections on this server.
    var playHistory = myServer.PlayHistory().Result;
    
    // Get Devices connected to this Server
    var devices = myServer.Devices().Result;
    
    // Get list of all Client objects connected to server.
    var clients = myServer.Clients().Result;
    
    // Scrobble Item on this server
    myServer.ScrobbleItem("123");

    // UnScrobble Item on this server
    myServer.UnScrobbleItem("123");

    // Downloads Server Logs
    var logs = myServer.DownloadLogs().Result;
    
    // Get list of all release updates available for this Server
    var updates = myServer.CheckForUpdate().Result;
    
    // Get Server Activities.
    var activities = myServer.Activities().Result;

    // Get Server Statistics.
    var statistics = myServer.Activities().Result;
    
    // Force Plex Server to download new SyncList from Plex.tv.
    myServer.RefreshSyncList();
    
    // Force Plex Server to refresh content for known SyncLists.
    myServer.RefreshContent();
    
    // Force Plex Server to download new SyncList and refresh content.
    myServer.RefreshSync();
    
    // Get Transcode Sessions
    var transcodeSessions = myServer.TranscodeSessions().Result;
    
    // Get Server active Sessions
    var sessions = myServer.Sessions().Result;
    
    // Get Server Playlists
    var playlists = myServer.Playlists().Result;

Library Documentation

    var servers = account.Servers().Result;
    var myServer = servers.Where(c=>c.Owned == "1").First();
     
    // Get Libraries for server
    var libraries = myServer.Libraries().Result;
    
     // Get Movies library
    var movieLibrary = libraries.Single(c => c.Title == "Movies");
  
    // Get Search Filters available for this Library
    var filters = movieLibrary.SearchFilters().Result;
  
    // Search Library for item
    string title = "Harry Potter";
    string sort = "rating:desc";
    string libraryType = "movie";
    var items = movieLibrary.Search(title, sort, libraryType).Result;
 
    // Get Recently Added for Library
    var recentlyAdded = movieLibrary.RecentlyAdded().Result;
    
    // Return list of Hubs on this library along with their Metadata items
    var hubs = movieLibrary.Hubs();
    
    // Empty Trash for this Library
    movieLibrary.EmptyTrash();
    
    // Scan for new items on this Library
    movieLibrary.ScanForNewItems();
    
    // Cancel running Scan on this library
    movieLibrary.CancelScan();

#OLD DOCUMENTATION (NEED TO UPDATE)

Metadata

    var plexApi = ServiceProvider.GetService<IPlexClient>();
         
    // Get Metadata for Library
    var metadatas = plexApi.MetadataForLibraryAsync(string authToken, string plexServerHost, string libraryKey).Result;
  
    // Get Children for Metadata by Metadata Key
    var metadatas = plexApi.GetChildrenMetadataAsync(string authToken, string plexServerHost, int metadataKey).Result;

    // Get Metadata by Key
    var metadata = plexApi.GetMetadataAsync(string authToken, string plexServerHost, int metadataKey).Result;

    // Search
    var metadatas = plexApi.SearchAsync(string authToken, string plexServerHost, string query).Result;   

Sessions

    var plexApi = ServiceProvider.GetService<IPlexClient>();
    
    // Get All Sessions on Server
    var sessions = plexApi.GetSessionsAsync(string authToken, string plexServerHost).Result;
    
    // Get Session for Player Machine Id
    var session = plexApl.GetSessionByPlayerIdAsync(string authToken, string plexServerHost, string playerKey).Result;

Collections

    var plexApi = ServiceProvider.GetService<IPlexClient>();
    
    // Get Collections for Library
    var collections = plexApi
        .GetCollections(authKey, plexServerUrl, libraryKey).Result;
        
    // Get Collection Tags for Movie
    var collectionTags = plexApi.GetCollectionTagsForMovieAsync(authKey, plexServerUrl, movieKey).Result;
        
    // Get Collection
    var collection = plexApi.GetCollectionAsync(authKey, plexServerUrl, collectionKey).Result;    
    
    // Get Collection Movies
    var movies = plexApi.GetCollectionMoviesAsync(authKey, plexServerUrl, collectionKey).Result;

    // Delete Collection from Movie
    plexApi.DeleteCollectionFromMovieAsync(authKey, plexServerUrl, libraryKey, movieKey, collectionName);
    
    // Add Collection to Movie
    plexApi.AddCollectionToMovieAsync(authKey, plexServerUrl, libraryKey, movieKey, collectionName);

    // Update Collection
    var collection = plexApi.GetCollectionAsync(authKey, fullUri, collectionRatingKey).Result;
    collection.Title = "New Title for Collection";
    plexApi.UpdateCollection(authKey, plexServerUrl, libraryKey, collection);

OAuth Implementation Example

    public class PlexLoginController : Controller
    {
        private readonly HttpClient _httpClient = new HttpClient();
        private readonly PlexOAuthClient _plexOAuthClient;
        private readonly IPlexClient _plexClient;

        public PlexLoginController(PlexOAuthClient plexOAuthClient, IPlexClient plexClient)
        {
            _plexOAuthClient = plexOAuthClient;
            _plexClient = plexClient;
        }

        public async Task<IActionResult> IndexAsync()
        {
            var redirectUrl = Url.Action("PlexReturn", "PlexLogin", null, Request.Scheme);
            var oauthUrl = await _plexClient.CreateOAuthPinAsync(redirectUrl);
            HttpContext.Session.SetString("PlexOauthId", oauthUrl.Id.ToString());
            return Redirect(oauthUrl.Url);
        }

        public async Task<IActionResult> PlexReturn()
        {
            var oauthId = HttpContext.Session.GetString("PlexOauthId");
            var oAuthPin = await _plexClient.GetAuthTokenFromOAuthPinAsync(oauthId);

            if (string.IsNullOrEmpty(oAuthPin.AuthToken))
                throw new Exception("Plex auth failed.");
            HttpContext.Session.Remove("PlexOauthId");
            HttpContext.Session.SetString("PlexKey", oAuthPin.AuthToken);

            return Redirect("/plex");
        }
    }