# Plex API Quick Reference This document provides a curated reference for the most commonly used Plex Media Server API endpoints. Use this with the `plex_api_call` tool for operations not covered by specific tools. ## Authentication All requests require these headers (handled automatically by this MCP server): - `X-Plex-Token`: Authentication token - `X-Plex-Client-Identifier`: Unique client ID - `Accept: application/json`: Request JSON responses ## Pagination Many endpoints support pagination via headers: - `X-Plex-Container-Start`: Starting offset (0-based) - `X-Plex-Container-Size`: Number of items to return --- ## Libraries ### List All Libraries ``` GET /library/sections/all ``` Returns all library sections (Movies, TV Shows, Music, etc.) ### Get Library Details ``` GET /library/sections/{sectionId} ``` Get details about a specific library section. ### List Library Contents ``` GET /library/sections/{sectionId}/all ``` List all items in a library. Supports filtering and sorting. Query params: - `type`: Filter by type (1=movie, 2=show, 4=episode, 8=artist, 9=album, 10=track) - `sort`: Sort field (e.g., `titleSort`, `addedAt:desc`, `year`) - `X-Plex-Container-Start`: Pagination start - `X-Plex-Container-Size`: Page size ### Refresh Library (Scan) ``` POST /library/sections/{sectionId}/refresh ``` Trigger a library scan for new content. Query params: - `force=1`: Force metadata refresh even if files unchanged - `path`: Restrict scan to specific path ### Cancel Library Refresh ``` DELETE /library/sections/{sectionId}/refresh ``` --- ## Metadata ### Get Item Metadata ``` GET /library/metadata/{ratingKey} ``` Get detailed metadata for a specific item. ### Get Children ``` GET /library/metadata/{ratingKey}/children ``` Get children of an item (e.g., seasons of a show, episodes of a season). ### Get All Leaves ``` GET /library/metadata/{ratingKey}/allLeaves ``` Get all leaf items (e.g., all episodes of a show). ### Refresh Item Metadata ``` POST /library/metadata/{ratingKey}/refresh ``` Refresh metadata for a specific item. --- ## Search ### Global Search ``` GET /hubs/search?query={searchTerm} ``` Search across all libraries. Query params: - `query`: Search term (required) - `limit`: Max results per type - `sectionId`: Restrict to specific library ### Voice Search ``` GET /hubs/search/voice?query={searchTerm} ``` --- ## Hubs (Discovery) ### Get All Hubs ``` GET /hubs ``` Get discovery hubs (Continue Watching, Recently Added, etc.) ### Continue Watching ``` GET /hubs/continueWatching ``` ### Library Hubs ``` GET /hubs/sections/{sectionId} ``` Get hubs for a specific library. --- ## Playback Tracking ### Mark as Played (Scrobble) ``` GET /:scrobble?key={ratingKey}&identifier=com.plexapp.plugins.library ``` ### Mark as Unplayed ``` GET /:unscrobble?key={ratingKey}&identifier=com.plexapp.plugins.library ``` ### Update Timeline ``` GET /:timeline ``` Report playback progress. Query params: - `ratingKey`: Item key - `key`: Full key path - `state`: playing, paused, stopped - `time`: Current position in ms - `duration`: Total duration in ms --- ## Ratings ### Rate an Item ``` PUT /:rate?key={ratingKey}&identifier=com.plexapp.plugins.library&rating={value} ``` Rating value: 0-10 (0 removes rating) --- ## Playlists ### List Playlists ``` GET /playlists ``` Query params: - `playlistType`: audio, video, photo - `smart`: 0 or 1 ### Get Playlist ``` GET /playlists/{playlistId} ``` ### Get Playlist Items ``` GET /playlists/{playlistId}/items ``` ### Create Playlist ``` POST /playlists ``` Query params: - `title`: Playlist name - `type`: audio, video, photo - `smart`: 0 or 1 - `uri`: Items to add (server://...) ### Add to Playlist ``` PUT /playlists/{playlistId}/items?uri={itemUri} ``` ### Delete Playlist ``` DELETE /playlists/{playlistId} ``` --- ## Collections ### List Collections ``` GET /library/sections/{sectionId}/collections ``` ### Get Collection Items ``` GET /library/collections/{collectionId}/items ``` ### Add to Collection ``` PUT /library/collections/{collectionId}/items?uri={itemUri} ``` ### Remove from Collection ``` DELETE /library/collections/{collectionId}/items/{itemId} ``` --- ## Play Queues ### Create Play Queue ``` POST /playQueues ``` Query params: - `uri`: Source URI - `type`: audio, video, photo - `shuffle`: 0 or 1 - `repeat`: 0, 1, 2 - `continuous`: 0 or 1 ### Get Play Queue ``` GET /playQueues/{playQueueId} ``` --- ## Server Status ### Server Identity ``` GET /identity ``` Basic server info (machine identifier, version). ### Server Capabilities ``` GET / ``` Full server capabilities and features. ### Server Preferences ``` GET /:prefs ``` --- ## Activities ### List Activities ``` GET /activities ``` Get running activities (transcoding, scanning, etc.) ### Cancel Activity ``` DELETE /activities/{activityId} ``` --- ## Butler (Scheduled Tasks) ### Get Butler Status ``` GET /butler ``` List scheduled maintenance tasks. ### Run Butler Task ``` POST /butler/{taskName} ``` Task names: BackupDatabase, BuildGracenoteCollections, CheckForUpdates, CleanOldBundles, CleanOldCacheFiles, DeepMediaAnalysis, GenerateAutoTags, GenerateChapterThumbs, GenerateMediaIndexFiles, OptimizeDatabase, RefreshLibraries, RefreshLocalMedia, RefreshPeriodicMetadata, UpgradeMediaAnalysis ### Stop Butler Task ``` DELETE /butler/{taskName} ``` --- ## Transcoding ### Get Transcode Sessions ``` GET /transcode/sessions ``` ### Stop Transcode Session ``` DELETE /transcode/sessions/{sessionKey} ``` --- ## Metadata Types Reference | Type | Number | Description | |------|--------|-------------| | movie | 1 | Movies | | show | 2 | TV Shows | | season | 3 | Seasons | | episode | 4 | Episodes | | trailer | 5 | Trailers | | artist | 8 | Music Artists | | album | 9 | Music Albums | | track | 10 | Music Tracks | | photo | 13 | Photos | | photoalbum | 14 | Photo Albums | | playlist | 15 | Playlists | | collection | 18 | Collections | --- ## Common Query Parameters Many list endpoints accept these query parameters: - `type`: Filter by metadata type number - `sort`: Sort field with optional `:asc` or `:desc` - `X-Plex-Container-Start`: Pagination offset - `X-Plex-Container-Size`: Items per page - `includeChildren`: Include child items (1/0) - `includeElements`: Comma-separated list of elements to include - `excludeElements`: Comma-separated list of elements to exclude --- ## URI Format When referencing items for playlists/queues: ``` server://{machineIdentifier}/com.plexapp.plugins.library/library/metadata/{ratingKey} ``` Get machine identifier from `GET /identity`.