Plex API Guide -- Automating Your Media Server

Plex Media Server exposes a comprehensive HTTP API that lets you do almost anything you can do through the web interface and more. Trigger library scans, fetch metadata, manage playlists, monitor active sessions, and automate maintenance tasks -- all through standard HTTP requests. This guide covers authentication, key endpoints, practical examples with curl and Python, and common automation use cases.

Authentication -- Getting Your X-Plex-Token

Every API request to a Plex server requires authentication via an X-Plex-Token parameter. This token identifies your Plex account and grants access to servers claimed by that account. There are several ways to obtain your token.

Method 1: From the Plex Web Interface

The quickest way to find your token is through the Plex web app. Open any media item in your browser, click the three-dot menu, and select "Get Info." Look at the XML URL in your browser's address bar -- the X-Plex-Token parameter will be appended to the URL.

Method 2: Via the plex.tv API

You can authenticate against plex.tv to receive a token programmatically:

curl -X POST "https://plex.tv/users/sign_in.json" \
  -H "X-Plex-Client-Identifier: my-automation-script" \
  -H "X-Plex-Product: My Script" \
  -H "X-Plex-Version: 1.0" \
  -d "user[login]=your_email" \
  -d "user[password]=your_password"

The response JSON includes an authToken field. This is your global Plex account token. Note that for direct server communication, especially when working with shared user accounts, you may need a server-specific token obtained from the /api/v2/resources endpoint.

Important: Account Token vs. Server Token

The global authToken from plex.tv works for the server owner's account. If you are building an application that works with shared users (users who have been invited to access a server but do not own it), you need to obtain a serverToken from the /api/v2/resources endpoint. The server token is scoped to a specific server and user combination.

Key API Endpoints

All endpoints are relative to your server's base URL, typically http://server-ip:32400. Append ?X-Plex-Token=YOUR_TOKEN to every request, or pass it as a header: X-Plex-Token: YOUR_TOKEN.

Server Identity

GET /identity

Returns server name, version, platform, and machine identifier. Useful for verifying connectivity and identifying which server you are talking to.

List Libraries

GET /library/sections

Returns all libraries on the server with their keys, types, titles, and paths. Each library has a numeric key (e.g., 1, 2, 3) that you use in subsequent requests.

Browse a Library

GET /library/sections/{key}/all

Returns all items in a library. Add query parameters to filter: ?type=1 for movies, ?type=4 for episodes. You can also filter by year, genre, rating, and other metadata fields.

Get Item Metadata

GET /library/metadata/{ratingKey}

Returns full metadata for a specific item, including file paths, codec information, artwork URLs, and all associated metadata.

Active Sessions

GET /status/sessions

Returns information about all active playback sessions, including the user, client device, media being played, transcoding status, and bandwidth usage.

Trigger a Library Scan

GET /library/sections/{key}/refresh

Triggers a scan of the specified library. Plex will check for new, changed, and removed files.

Practical Examples with curl

List All Movie Libraries

curl -s "http://192.168.1.100:32400/library/sections" \
  -H "X-Plex-Token: YOUR_TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool

Search for a Movie

curl -s "http://192.168.1.100:32400/library/sections/1/all?title=Inception" \
  -H "X-Plex-Token: YOUR_TOKEN" \
  -H "Accept: application/json"

Check Who Is Currently Streaming

curl -s "http://192.168.1.100:32400/status/sessions" \
  -H "X-Plex-Token: YOUR_TOKEN" \
  -H "Accept: application/json"

Force a Library Scan

curl -s "http://192.168.1.100:32400/library/sections/1/refresh" \
  -H "X-Plex-Token: YOUR_TOKEN"

Python Automation Examples

For more complex automation, Python with the requests library is the natural choice. Here is a script that monitors active sessions and sends a notification when a new stream starts:

import requests
import time

PLEX_URL = "http://192.168.1.100:32400"
TOKEN = "YOUR_TOKEN"
HEADERS = {
    "X-Plex-Token": TOKEN,
    "Accept": "application/json"
}

known_sessions = set()

while True:
    r = requests.get(f"{PLEX_URL}/status/sessions", headers=HEADERS)
    data = r.json()

    current = set()
    for session in data.get("MediaContainer", {}).get("Metadata", []):
        session_id = session.get("sessionKey")
        current.add(session_id)

        if session_id not in known_sessions:
            user = session.get("User", {}).get("title", "Unknown")
            title = session.get("title", "Unknown")
            print(f"New stream: {user} is watching {title}")

    known_sessions = current
    time.sleep(30)

You can extend this pattern to send notifications via Discord webhooks, email, or any other service. Tautulli provides this functionality out of the box (see our Tautulli guide), but building your own gives you full control.

Plex Webhooks

Plex Pass subscribers can configure server-side webhooks that fire on events like playback start, stop, pause, resume, media added, and library scan complete. Configure these in Settings > Webhooks by adding a URL that Plex will POST to when events occur.

The webhook payload is a JSON body containing the event type, account information, server details, and metadata about the media item involved. Common automation triggers include:

• media.play: Send a notification when someone starts watching something.
• library.new: Trigger a custom script when new media is added (e.g., sync artwork, update a database, notify a chat channel).
• media.scrobble: Log completed views to an external service.
• device.new: Alert when a new device connects to your server.

Common Automation Use Cases

• Scheduled library scans. Trigger scans at specific times using cron and the refresh endpoint, rather than relying on Plex's built-in interval scanner.
• User activity reports. Query the sessions endpoint periodically and log usage to a database for monthly reports.
• Automated poster management. Use the metadata endpoints to bulk-update artwork across your library.
• Disk space monitoring. Query library sizes and file counts, then alert when storage is running low.
• Stale content cleanup. Identify items that have not been played in a specified period and flag them for removal.

The Plex API is not officially documented by Plex in a formal specification, but community resources like the unofficial Plex API documentation on GitHub provide comprehensive endpoint references. Combined with the Python plexapi library (installable via pip install plexapi), you can automate virtually every aspect of your Plex server management.

Related Articles