plex-mcp/docs/api_reference.md

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.