# Plex Media Server

Monitor your entire Plex library, track recently added content, and discover what to watch next with AI-powered insights.

Connect Weavestream to your Plex Media Server to monitor:

• 🎬 Movies - Your complete movie library with metadata
• 📺 TV Shows - All TV series and episodes
• 🎵 Music - Music library and playlists
• 📥 Recently Added - New content as it's added to your server
• ▶️ Now Playing - Currently streaming content
• 👥 Watch History - What you and your users have watched

Estimated Setup Time: 10 minutes

• Plex Media Server installed and running
• Admin access to your Plex server
• Network access to your Plex server (local or remote)
• Weavestream installed on your Mac

Plex uses a token-based authentication system. Here's how to get your token:

1. Open Plex Web App in your browser
2. Go to any item in your library (movie, show, etc.)
3. Click the "..." (three dots) menu
4. Select "Get Info"
5. Click "View XML" at the bottom
6. Look at the URL in your browser's address bar
7. Find the X-Plex-Token= parameter in the URL
8. Copy everything after X-Plex-Token= until the next & or end of URL

Example URL:

http://192.168.1.3:32400/library/metadata/12345?X-Plex-Token=abc123xyz789

Your token is: abc123xyz789

macOS/Linux:

cat ~/Library/Application\ Support/Plex\ Media\ Server/Preferences.xml | grep -oP 'PlexOnlineToken="\K[^"]+'

Windows:

%LOCALAPPDATA%\Plex Media Server\Preferences.xml

Open in text editor and find PlexOnlineToken="YOUR_TOKEN_HERE"

1. Go to https://plex.tv/users/sign_in
2. Sign in with your Plex account
3. After signing in, your token will be visible in the page source (Inspect Element)
4. Or use this curl command:

curl -X POST \
  'https://plex.tv/users/sign_in.json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'user[login]=YOUR_EMAIL&user[password]=YOUR_PASSWORD'

Look for "authToken" in the response.

If Weavestream is on the same network as your Plex server:

Format:

http://[SERVER_IP]:32400

Common examples:

http://192.168.1.3:32400
http://localhost:32400
http://10.0.0.50:32400

How to find your server IP:

1. Open Plex Web App
2. Go to Settings → Network
3. Look for "LAN Networks" or check your router's DHCP table
4. Default port is always 32400

If accessing Plex remotely:

Format:

https://[UNIQUE_URL].plex.direct:32400

How to find:

1. Open Plex Web App
2. Go to Settings → Network
3. Look for "Custom server access URLs"
4. Use the HTTPS URL listed

Example:

https://abc-123-xyz-789.1234567890abcdef.plex.direct:32400

Plex organizes content into library sections (Movies, TV Shows, Music, etc.). You need the section IDs to query specific libraries.

Option 1: Via Browser

1. Open your browser
2. Go to: http://YOUR_SERVER_IP:32400/library/sections?X-Plex-Token=YOUR_TOKEN
3. You'll see XML (or JSON if you add header X-Plex-Format: json)
4. Look for <Directory> tags with key attributes

Example Response:

<Directory key="1" type="movie" title="Movies" />
<Directory key="2" type="show" title="TV Shows" />
<Directory key="3" type="artist" title="Music" />

Your section IDs:

• Movies: 1
• TV Shows: 2
• Music: 3

Option 2: Via Terminal

curl "http://YOUR_SERVER_IP:32400/library/sections?X-Plex-Token=YOUR_TOKEN" \
  -H "X-Plex-Format: json" | jq '.MediaContainer.Directory[] | {key, title, type}'

1. Open Weavestream
2. Click the "+" button in the sidebar
3. Select "Add Source"
4. Fill in the source details:
   • Name: Plex
   • Base URL: http://192.168.1.3:32400 (use your server URL)
   • Auth Type: Query Parameter
   • Query Param Name: X-Plex-Token
   • Query Param Value: Paste your Plex token
   • Custom Headers:
     • Header Name: X-Plex-Format
     • Header Value: json
   • Icon: Select tv or film or custom plex icon if available
   • Color: Choose your preference (suggested: #FF9500 - Plex orange, or #E5A00D - gold)
   • Refresh Interval: 60 minutes (Plex libraries don't change frequently)
5. Click "Add" or "Save"

Now we'll add endpoints to monitor different aspects of your Plex library.

Get all recently added content across all libraries.

Configuration:

• Name: Recently Added
• Path: /library/recentlyAdded
• Method: GET
• Query Parameters: (none needed - token is in source config)

Field Mapping:

• Array Path: MediaContainer.Metadata (Plex wraps results in this structure)
• ID Field: ratingKey
• Title Field: title
• Date Field: addedAt (Unix timestamp)
• Summary Fields: summary, year, contentRating
• Status Field: (none)

Retention Mode: Keep All (preserve history of additions)

Get your complete movie library.

Configuration:

• Name: All Movies
• Path: /library/sections/{SECTION_ID}/all

Replace {SECTION_ID} with your Movies section ID (usually 1)

Example: /library/sections/1/all

Query Parameters:

• type: 1 (optional - filters to movies only)

Field Mapping:

• Array Path: MediaContainer.Metadata
• ID Field: ratingKey
• Title Field: title
• Date Field: addedAt
• Summary Fields: summary, year, studio, contentRating, rating
• Status Field: (none)

Retention Mode: Delete on Sync (replaces full library each time)

Get your complete TV show library.

Configuration:

• Name: All TV Shows
• Path: /library/sections/{SECTION_ID}/all

Replace {SECTION_ID} with your TV Shows section ID (usually 2)

Example: /library/sections/2/all

Query Parameters:

• type: 2 (filters to TV shows)

Field Mapping:

• Array Path: MediaContainer.Metadata
• ID Field: ratingKey
• Title Field: title
• Date Field: addedAt
• Summary Fields: summary, year, studio, contentRating, leafCount (episode count)
• Status Field: (none)

Retention Mode: Delete on Sync

See what's currently streaming on your Plex server.

Configuration:

• Name: Now Playing
• Path: /status/sessions
• Method: GET
• Query Parameters: (none)

Field Mapping:

• Array Path: MediaContainer.Metadata
• ID Field: sessionKey
• Title Field: title
• Date Field: (use sync time)
• Summary Fields: User.title (username), Player.title (device), Player.state (playing/paused)
• Status Field: (none)

Retention Mode: Delete on Sync (only current sessions matter)

Note: This endpoint only returns data when something is actively playing.

Movies you haven't watched yet.

Configuration:

• Name: Unwatched Movies
• Path: /library/sections/{SECTION_ID}/unwatched
• Method: GET

Replace {SECTION_ID} with your Movies section ID

Query Parameters: (none)

Field Mapping: Same as "All Movies"

Retention Mode: Delete on Sync

Content you've started but haven't finished.

Configuration:

• Name: On Deck
• Path: /library/onDeck
• Method: GET
• Query Parameters: (none)

Field Mapping:

• Array Path: MediaContainer.Metadata
• ID Field: ratingKey
• Title Field: title
• Date Field: lastViewedAt
• Summary Fields: summary, viewOffset (where you left off)

Track what you've recently watched.

Configuration:

• Name: Watch History
• Path: /status/sessions/history/all
• Method: GET

Query Parameters:

• sort: viewedAt:desc (newest first)

Field Mapping:

• Array Path: MediaContainer.Metadata
• ID Field: historyKey
• Title Field: title
• Date Field: viewedAt
• Summary Fields: accountID, deviceID

Get movies by genre.

Configuration:

• Name: Action Movies
• Path: /library/sections/{SECTION_ID}/all
• Method: GET

Query Parameters:

• genre: 28 (Action genre ID - varies, use genre endpoint to find IDs)

Field Mapping: Same as "All Movies"

{
  "MediaContainer": {
    "Metadata": [
      {
        "ratingKey": "12345",
        "key": "/library/metadata/12345",
        "guid": "plex://movie/5d776...",
        "title": "The Matrix",
        "summary": "A computer hacker learns...",
        "year": 1999,
        "addedAt": 1706284800,
        "updatedAt": 1706284801,
        "contentRating": "R",
        "rating": 8.7,
        "studio": "Warner Bros.",
        "duration": 8160000,
        "thumb": "/library/metadata/12345/thumb/1706284801",
        "art": "/library/metadata/12345/art/1706284801",
        "Genre": [
          {"tag": "Action"},
          {"tag": "Sci-Fi"}
        ],
        "Director": [
          {"tag": "Lana Wachowski"}
        ],
        "Writer": [
          {"tag": "Lana Wachowski"}
        ],
        "Country": [
          {"tag": "United States of America"}
        ],
        "Role": [
          {"tag": "Keanu Reeves"},
          {"tag": "Laurence Fishburne"}
        ]
      }
    ]
  }
}

Key Fields:

• ratingKey - Unique ID for the item
• title - Movie/show title
• addedAt - Unix timestamp when added to library
• year - Release year
• rating - User/community rating (0-10)
• summary - Plot description
• duration - Length in milliseconds

{
  "ratingKey": "67890",
  "title": "Breaking Bad",
  "summary": "A high school chemistry teacher...",
  "year": 2008,
  "leafCount": 62,
  "viewedLeafCount": 45,
  "childCount": 5,
  "Genre": [
    {"tag": "Crime"},
    {"tag": "Drama"}
  ]
}

TV-Specific Fields:

• leafCount - Total episodes
• viewedLeafCount - Episodes you've watched
• childCount - Number of seasons

1. Under Plex source, click "+" → "New Filter"
2. Name: New Movies - This Month
3. Select Endpoint: All Movies
4. Add Condition:
   • Field: addedAt
   • Operator: in last
   • Value: 30 days
5. Save

1. Create new filter
2. Name: Highly Rated Movies
3. Select Endpoint: All Movies
4. Add Condition:
   • Field: rating
   • Type: Number
   • Operator: greater than or equal
   • Value: 8.0
5. Save

1. Create new filter
2. Name: Unwatched 4K Movies
3. Select Endpoint: All Movies
4. Add Conditions:
   • Field: Media.videoResolution
   • Operator: equals
   • Value: 4k
   • AND
   • Field: viewCount
   • Operator: equals
   • Value: 0
5. Save

1. Create new filter
2. Name: 80s Movies
3. Select Endpoint: All Movies
4. Add Conditions:
   • Field: year
   • Operator: greater than or equal
   • Value: 1980
   • AND
   • Field: year
   • Operator: less than
   • Value: 1990
5. Save

1. Create new filter
2. Name: Watched This Week
3. Select Endpoint: Watch History
4. Add Condition:
   • Field: viewedAt
   • Operator: in last
   • Value: 7 days
5. Save

Now you can ask intelligent questions about your Plex library!

Discovery:

• "What movies did I add recently?"
• "Show me highly rated sci-fi movies"
• "Find comedies from the 90s"
• "What 4K movies haven't I watched yet?"
• "Recommend something based on movies I've rated highly"

Library Management:

• "How many movies do I have?"
• "What's my biggest genre collection?"
• "Show me movies I added but never watched"
• "What's the oldest movie in my library by release date?"

Watch Planning:

• "What should I watch tonight?"
• "Find short movies under 90 minutes"
• "Show me movies I started but didn't finish"
• "What critically acclaimed movies haven't I seen?"

Analysis:

• "What genres do I collect the most?"
• "Show me all Christopher Nolan movies"
• "Find movies starring Tom Hanks"
• "What's my average movie rating?"

Family/Kids:

• "Show me G-rated movies"
• "Find animated movies for kids"
• "What family-friendly content did I add this month?"

Metadata Queries:

• "Which movies don't have posters?"
• "Show me movies with no summary"
• "Find duplicate movies in my library"

Plex API supports various query parameters:

Sorting:

sort: titleSort           - By title A-Z
sort: addedAt:desc       - Newest additions first
sort: rating:desc        - Highest rated first
sort: year:desc          - Newest releases first
sort: viewCount:desc     - Most watched first

Filtering:

unwatched: 1             - Only unwatched
duplicate: 1             - Only duplicates
genre: Action            - By genre name
year: 2024              - By release year
decade: 2020            - By decade
contentRating: R        - By rating (G, PG, PG-13, R)
resolution: 4k          - By video quality

Limiting:

X-Plex-Container-Start: 0    - Pagination start
X-Plex-Container-Size: 50    - Results per page

When using type parameter:

Plex artwork URLs need to be constructed:

Format:

{BASE_URL}{thumb}?X-Plex-Token={TOKEN}

Example:

http://192.168.1.3:32400/library/metadata/12345/thumb/1706284801?X-Plex-Token=abc123

You can add these as summary fields for display.

If you have multiple Plex servers or libraries:

Create separate sources:

• Source 1: "Plex - Main Server" (home server)
• Source 2: "Plex - Remote Server" (friend's server)
• Each with its own base URL and token

Create endpoints for each library section:

• Movies (Section 1)
• TV Shows (Section 2)
• Music (Section 3)
• Family Movies (Section 4)
• 4K Movies (Section 5)

Each endpoint uses the appropriate section ID in the path.

Solution:

1. Verify your Plex token is correct
2. Check token is added as query parameter named X-Plex-Token
3. Ensure you have permission to access the server
4. Try generating a new token

Solution:

1. Verify your library section ID is correct
2. Check that the library actually has content
3. Add header X-Plex-Format: json to get JSON instead of XML
4. Test the URL directly in your browser first

Solution:

1. Verify Plex Media Server is running
2. Check the base URL and port (default: 32400)
3. If remote: Ensure Remote Access is enabled in Plex settings
4. Check firewall isn't blocking port 32400
5. Try http://localhost:32400 if on same machine

Solution:

1. Plex wraps all results in MediaContainer.Metadata
2. Make sure Array Path is set to exactly: MediaContainer.Metadata
3. Check raw JSON response to verify structure

Solution:

1. Plex uses Unix timestamps (seconds since 1970)
2. The addedAt field should auto-convert
3. If issues persist, check if your Plex version uses milliseconds instead

Solution:

1. Add custom header: X-Plex-Format with value json
2. This header must be set in the Source configuration
3. Without it, Plex returns XML by default

Pros:

• Faster response times
• No internet dependency
• More secure (data stays local)

Cons:

• Only works on same network
• Requires port forwarding for remote access

Pros:

• Access from anywhere
• Works across networks

Cons:

• Slower (internet dependent)
• Exposes server to internet (use strong password)

Best Practice:

• Use local URL (http://192.168.x.x:32400) when on same network
• Use Plex's secure remote URLs for external access
• Consider VPN for secure remote access instead of exposing server

Important:

• Plex tokens grant full access to your server
• Never share your token
• Rotate tokens if exposed
• Revoke tokens you're not using

To revoke tokens:

1. Plex Web → Settings → Authorized Devices
2. Remove devices/apps you don't recognize

Path: /playlists

Get all playlists you've created.

Path: /library/sections/{SECTION_ID}/collections

Get movie/show collections (e.g., Marvel Cinematic Universe).

Path: /library/sections/{SECTION_ID}/recommended

Plex's recommendations based on your viewing.

Path: /search
Query: query=matrix

Search across all libraries.

Path: /identity

Get server name, version, unique ID.

Path: /library/sections

List all library sections on your server.

Tip 1: Adjust Refresh Intervals

• Recently Added: 30-60 minutes
• Full Libraries: 4-6 hours (libraries don't change often)
• Now Playing: 5 minutes (for real-time monitoring)

Tip 2: Limit Results Use X-Plex-Container-Size header to limit results if you have huge libraries.

Tip 3: Cache Artwork If displaying posters, cache them locally to reduce server load.

Tip 4: Use Filters Over Endpoints Instead of creating separate endpoints for "Unwatched", "High Rated", etc., create one "All Movies" endpoint and use Smart Filters.

Before you finish, verify:

• ✅ Plex token obtained and saved securely
• ✅ Server URL identified (local or remote)
• ✅ Library section IDs determined
• ✅ Plex source added to Weavestream
• ✅ Custom header X-Plex-Format: json configured
• ✅ Recently Added endpoint syncing
• ✅ At least one library endpoint (Movies or TV Shows) syncing
• ✅ Array path set to MediaContainer.Metadata
• ✅ Smart filters created for discovery
• ✅ Tested AI questions about your library

You're all set! Discover what to watch with AI-powered insights! 🎬

Last updated: February 2026 Plex Media Server API version: Compatible with all modern Plex versions