Ben
25f2658dcb
All checks were successful
Build and Push Plex MCP Docker Image / build (push) Successful in 35s
- get_libraries: List all library sections - search_library: Search for media by title - get_metadata: Get detailed item info by rating key - get_recently_added: Get recently added content - refresh_library: Trigger library scan - plex_api_call: Raw API passthrough for any endpoint - search_api_docs: Search OpenAPI spec for endpoint documentation Includes Docker support and Gitea Actions workflow for container builds.
367 lines
6.5 KiB
Markdown
367 lines
6.5 KiB
Markdown
# 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`.
|