Plex Media Server URL Commands

If you're familiar with interpreting XML, you can gather information about your Plex Media Server. You might like to do this if you're troubleshooting a problem or if you're a Developer.

Basic Information

You'll Need Your Token

In a default setup, all of your requests to the Plex Media Server must be authenticated. In this case, that means that you need to include a valid authentication token.

Simply add your token as an X-Plex-Token parameter in the URL similar to this:

http://[PMS_IP_Address]:32400/library/sections?X-Plex-Token=YourTokenGoesHere

Related Page: Finding an authentication token / X-Plex-Token

Base Server Capabilities

Each Plex Media Server has a number of capabilities as regards Transcoding and the Libraries it owns. To see the base information, visit the following URL:

http://[PMS_IP_Address]:32400/?X-Plex-Token=YourTokenGoesHere

Example:

<MediaContainer size="14" allowMediaDeletion="1" flashInstalled="1" friendlyName="PlexPMS"
machineIdentifier="62ad4ec510d34450a8d2a6ee04e195c515f65ddf" multiuser="1" myPlex="1" myPlexMappingState="mapped"
myPlexSigninState="ok" myPlexUsername="plexuser" platform="MacOSX" platformVersion="10.9.2" requestParametersInCookie="1"
silverlightInstalled="0" soundflowerInstalled="1" sync="1" transcoderActiveVideoSessions="0" transcoderAudio="1" transcoderVideo="1"
transcoderVideoBitrates="64,96,208,320,720,1500,2000,3000,4000,8000,10000,12000,20000"
transcoderVideoQualities="0,1,2,3,4,5,6,7,8,9,10,11,12" transcoderVideoResolutions="128,128,160,240,320,480,768,720,720,1080,1080,1080,1080"
updatedAt="1394559746" version="0.9.9.6.424-d1ab326" webkit="1">
   <Directory count="1" key="butler" title="butler"/>
   <Directory count="1" key="channels" title="channels"/>
   <Directory count="1" key="clients" title="clients"/>
   <Directory count="1" key="library" title="library"/>
   <Directory count="2" key="music" title="music"/>
   <Directory count="1" key="photos" title="photos"/>
   <Directory count="1" key="playQueues" title="playQueues"/>
   <Directory count="1" key="player" title="player"/>
   <Directory count="1" key="playlists" title="playlists"/>
   <Directory count="1" key="search" title="search"/>
   <Directory count="1" key="servers" title="servers"/>
   <Directory count="1" key="system" title="system"/>
   <Directory count="1" key="transcode" title="transcode"/>
   <Directory count="6" key="video" title="video"/>
</MediaContainer>

Listing Defined Libraries

A list of Libraries with details for each Library is available:

http://[PMS_IP_Address]:32400/library/sections?X-Plex-Token=YourTokenGoesHere

Gives the following result:

<MediaContainer size="3" allowSync="0" identifier="com.plexapp.plugins.library" mediaTagPrefix="/system/bundle/media/flags/"
mediaTagVersion="1390169701" title1="Plex Library">
   <Directory allowSync="0" art="/:/resources/movie-fanart.jpg" filters="1" refreshing="0" thumb="/:/resources/movie.png"
   key="29" type="movie" title="Movies" agent="com.plexapp.agents.imdb" scanner="Plex Movie Scanner"
   language="en" uuid="07a4b132-a67b-477e-a245-585935d08c0b" updatedAt="1394559305" createdAt="1390438950">
      <Location id="4" path="/Users/plexuser/Movies/Media/Movies"/>
   </Directory>
   <Directory allowSync="0" art="/:/resources/artist-fanart.jpg" filters="1" refreshing="0" thumb="/:/resources/artist.png"
   key="31" type="artist" title="Music" agent="com.plexapp.agents.lastfm" scanner="Plex Music Scanner"
   language="en" uuid="10254ef0-a0a4-481b-ad9c-46ab3db39d0b" updatedAt="1394039950"
   createdAt="1390440566">
      <Location id="7" path="/Users/plexuser/Movies/Media/Music"/>
   </Directory>
   <Directory allowSync="0" art="/:/resources/show-fanart.jpg" filters="1" refreshing="0" thumb="/:/resources/show.png"
   key="30" type="show" title="Television" agent="com.plexapp.agents.thetvdb" scanner="Plex Series Scanner"
   language="en" uuid="540e7c98-5a92-4e8f-b255-9cca2870060c" updatedAt="1394482680"
   createdAt="1390438925">
      <Location id="3" path="/Users/plexuser/Movies/Media/TV Shows"/>
   </Directory>
</MediaContainer>

Each Library has a Key that identifies it within the database. For example, the Movies Section above:

key="29" type="movie" title="Movies"

...indicates that the Key = 29, the type = movie and the title = Movies

Listing Section Contents

You can use the Section Key to further list its contents. This may be useful if you're investigating an issue. From the previous example, to list the Movies section contents:

http://[PMS_IP_Address]:32400/library/sections/29/all?X-Plex-Token=YourTokenGoesHere

...which returns (truncated for brevity):

<MediaContainer size="16" allowSync="1" art="/:/resources/movie-fanart.jpg" identifier="com.plexapp.plugins.library"
librarySectionID="29" librarySectionUUID="07a4b132-a67b-477e-a245-585935d08c0b"
mediaTagPrefix="/system/bundle/media/flags/" mediaTagVersion="1387854996" thumb="/:/resources/movie.png"
title1="Movies" title2="All Movies" viewGroup="movie" viewMode="65592">
   <Video ratingKey="56" key="/library/metadata/56" studio="Pixar" type="movie" title="A Bug's Life"
   titleSort="Bug's Life" contentRating="G" summary="On behalf of "oppressed bugs everywhere," an inventive ant
   named Flik hires a troupe of warrior bugs to defend his bustling colony from a horde of freeloading
   grasshoppers led by the evil-minded Hopper." rating="6.3000001907348597" year="1998"
   tagline="An epic of miniature proportions." thumb="/library/metadata/56/thumb/1394561225" art="/library/metadata/56/art/1394561225"
   duration="9685" originallyAvailableAt="1998-11-14" addedAt="1394561211" updatedAt="1394561225">
      <Media videoResolution="480" id="56" duration="9685" bitrate="1428" width="720" height="460" aspectRatio="1.85"
      audioChannels="2" audioCodec="aac" videoCodec="h264" container="mkv" videoFrameRate="24p">
         <Part id="64" key="/library/parts/64/file.mkv" duration="9685" file="/Users/plexuser/Movies/Media/Movies/A Bug's Life (1998).mkv"
         size="1728497" container="mkv"/>
      </Media>
      <Genre tag="Comedy"/>
      <Genre tag="Family"/>
      <Writer tag="Don McEnery"/>
      <Writer tag="Bob Shaw"/>
      <Director tag="John Lasseter"/>
      <Director tag="Andrew Stanton"/>
      <Country tag="USA"/>
      <Role tag="David Lander"/>
      <Role tag="Joe Ranft"/><Role tag="Jack Angel"/>
   </Video>
. . .

Listing an Item Details

Once you have listed the Library contents, you can gather information about an individual item within a Library. To do this:

  • List the Library
  • Find the media item you'd like to inspect
  • Find the item's key
  • List the details

For example, the following item has a key:

<Video ratingKey="1668" key="/library/metadata/1668"

To inspect the exhaustive details for this item:

http://[PMS_IP_ADDRESS]:32400/library/metadata/1668?X-Plex-Token=YourTokenGoesHere

Which yields the following (truncated for brevity):

<MediaContainer size="1" allowSync="1" identifier="com.plexapp.plugins.library" librarySectionID="29" librarySectionUUID="07a4b132-a67b-477e-a245-585935d08c0b" mediaTagPrefix="/system/bundle/media/flags/" mediaTagVersion="1387854996">
   <Video ratingKey="56" key="/library/metadata/56" studio="Pixar" type="movie" title="A Bug's Life"
   titleSort="Bug's Life" contentRating="G" summary="On behalf of "oppressed bugs everywhere," an inventive ant
   named Flik hires a troupe of warrior bugs to defend his bustling colony from a horde of freeloading
   grasshoppers led by the evil-minded Hopper." rating="6.3000001907348597" year="1998"
   tagline="An epic of miniature proportions." thumb="/library/metadata/56/thumb/1394561225" art="/library/metadata/56/art/1394561225"
   duration="9685" originallyAvailableAt="1998-11-14" addedAt="1394561211" updatedAt="1394561225">
      <Media videoResolution="480" id="56" duration="9685" bitrate="1428" width="720" height="460"
      aspectRatio="1.85" audioChannels="2" audioCodec="aac" videoCodec="h264" container="mkv" videoFrameRate="24p">
         <Part id="64" key="/library/parts/64/file.mkv" duration="9685" file="/Users/plexuser/Movies/Media/Movies/A Bug's Life (1998).mkv" size="1728497" container="mkv">
            <Stream id="219" streamType="1" codec="h264" index="0" bitrate="1428" language="English" languageCode="eng"
            anamorphic="1" bitDepth="8" cabac="1" chromaSubsampling="4:2:0" codecID="V_MPEG4/ISO/AVC" colorSpace="yuv"
            duration="9676" frameRate="29.970" frameRateMode="cfr" hasScalingMatrix="0" headerStripping="1" height="460" level="30"
            pixelAspectRatio="32:27" profile="main" refFrames="4" scanType="progressive" title="" width="720"/>
            <Stream id="220" streamType="2" selected="1" codec="aac" index="1" channels="2" language="English" languageCode="eng"
            codecID="A_AAC" duration="9685" profile="lc" samplingRate="48000" title=""/>
            <Stream id="221" streamType="2" codec="dca" index="2" channels="6" bitrate="1509"
            language="日本語 (にほんご/にっぽんご)" languageCode="jpn" bitDepth="24" bitrateMode="cbr" codecID="A_DTS"
            duration="9685" samplingRate="48000" title=""/>
         </Part>
      </Media>
      <Genre id="247" tag="Comedy"/>
      <Genre id="248" tag="Family"/>
      <Genre id="351" tag="Animation"/>
      <Genre id="352" tag="Adventure Film"/>
      <Writer id="356" tag="Don McEnery"/>
      <Producer id="401" tag="Kevin Reher"/>
      <Country id="253" tag="USA"/>
      <Role id="359" tag="David Lander" role="Thumper"/>
      <Role id="268" tag="Joe Ranft" role="Heimlich"/>
. . .
   </Video>
</MediaContainer>

Information in this view can be useful in a lot of situations. One particular situation where it comes in very handy is to verify what audio or subtitle streams Plex scanned in for the item. If you look at the <Stream> nodes, you'll see several useful pieces of information:

<Stream id="221" streamType="2" codec="dca" index="2" channels="6" bitrate="1509" language="日本語 (にほんご/にっぽんご)"
languageCode="jpn" bitDepth="24" bitrateMode="cbr" codecID="A_DTS" duration="9685" samplingRate="48000" title=""/>
  • streamType: The type of media stream/track it is (1 = video, 2 = audio, 3 = subtitle)
  • language: The display name for the language; typically associated with audio and subtitle streams
  • languageCode: The 3-letter ISO-639-2/B language code; typically associated with audio and subtitle streams

Scanning and Refreshing Sections

Update a Library

You can perform the same thing that occurs when you just press the Refresh button in the Plex Web App, which is to scan for changes and then refresh metadata for any new items.

Related Page: Plex Media Server > Libraries > Update or Refresh a Library

  • Determine the Library ID to scan
  • For example, the Movies Library above has an ID=29
http://[PMS_IP_ADDRESS]:32400/library/sections/29/refresh?X-Plex-Token=YourTokenGoesHere

Refresh an Entire Library

You can perform the same thing that occurs when you "Refresh All" a Library in the Plex Web App, which is to scan for changes and then refresh the metadata for all items in the Library, regardless of whether they already have metadata.

Related Page: Plex Media Server > Libraries > Update or Refresh a Library

  • Determine the Library ID to scan
  • For example, the Movies Library above has an ID=29
http://[PMS_IP_ADDRESS]:32400/library/sections/29/refresh?force=1&X-Plex-Token=YourTokenGoesHere