Add a Library

Before adding media to a Plex server, a library for the media type must first be created. The API command explained on this page will add a single library to a Plex server.

Since all media libraries are added in the same manner, this command can be complex as all options for each library type must be handled.

URL

POST http://{ip_address}:32400/library/sections?name={name}&type={type}&agent={agent}&scanner={scanner}&language={language}&location={media_location}&{preferences}&X-Plex-Token={plex_token}

Parameters

Return Status

Response

When a library is successfully created, an XML string value that contains information about the new library is returned:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="1">
    <Directory art="/:/resources/movie-fanart.jpg" composite="/library/sections/20/composite/1700011778" thumb="/:/resources/movie.png" key="20" type="movie" title="My Movies" agent="tv.plex.agents.movie" scanner="Plex Movie" language="en-US" uuid="23355a75-a85b-4420-8ed9-0a781010c8ad" updatedAt="1700011778" createdAt="1700011778" content="1" directory="1" contentChangedAt="0" hidden="0">
        <Location id="23" path="M:\Movies" />
    </Directory>
</MediaContainer>

If the library could not be created, string values are returned that explain the reasons why the library could not be created.

The XML returned contains information about the new library. The root is the MediaContainer element. This element contains only a single size attribute that indicates one Directory element was returned.

Within the MediaContainer there is one Directory element. The Directory element will contain information about the new library.

Within the Directory element there is one Location child element that provides information about the media files location for the library.

Remarks

Library Types

There are four types of libraries that can be added to Plex. When using the Web app to add a library, there are five types, but two use the same type when using the API.

The types are as follows:

The Value in the table above is what you would use in the API request to the Plex server.

Agents

Agents take information from the library scanner and then retrieve the metadata for each item in the library. A library can have one associated agent. One agent must be specified when adding a library, but can be changed later.

The tables in the next sections list the valid agents. The agents marked with "Default" are the agents selected when adding a library using the Plex Web app. Use the value in the "Value" column in the API request.

The valid agents for each library type are as follows:

Movies and other videos

TV shows

Music

Scanners

Library scanners are used to scan the media in the folders associated with the library and then pass that information to the agent.

The valid scanners for each media type are listed in the sections below. The ones marked with "Default" are the default scanners used when adding a library from the Plex Web app. You only include the scanner name in the request.

Movies and other videos

• Plex Movie (Default: Movies)
• Plex Movie Scanner
• Plex Video Files Scanner
• Plex Video Files Scanner (Default: Other videos)

TV shows

• Plex TV Series (Default)
• lex Series Scanner

Music

• Plex Music (Default)
• Plex Music Scanner

Library languages

All libraries require a language to be specified. The supported languages for a library are dependent on the type. For the "Other Videos" library, the only option available is "None", which means no true language can be selected.

The next few sections list all the available language options for each library type.

Movies and TV shows

Music and photos

Photos include all languages in the above table and the option of "None" in the next table.

Photos and other videos

Preferences

When adding a library using the Plex Web app there is an Advanced section that provides different options for each library type.

When using the API to add a library, these options are provided in the request in the form prefs[name]. Each preference option would be a separate parameter in the request.

There are default values for each preference and if you wish to use the default value then you wouldn't specify the preference in the request. This means that all preferences are optional if you just wish to use the default values.

Each library will have its own set of preferences, and some preferences can be set for different library types. The preferences are listed below.

Visibility

• Name: hidden
• Parameter Values:
  0 - (Default) Include in home screen and global search
  1 - Exclude from home screen
  2 - Exclude from home screen and global search
• Library Type: Moves, TV Shows, Music, Photos

Enable Cinema Trailers

• Name: enableCinemaTrailers
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Moves, Other Videos

Use original titles

• Name: originalTitles
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows

Prefer artwork based on library language

• Name: localizedArtwork
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies, TV Shows

Use local assets

• Name: useLocalAssets
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies, TV Shows

Prefer local metadata

• Name: respectTags
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows, Music

Find extras

• Name: useExternalExtras
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies, TV Shows

Only show trailers

• Name: skipNonTrailerExtras
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows

Allow red band trailers

• Name: useRedbandTrailers
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows

Localized subtitles

• Name: includeExtrasWithLocalizedSubtitles
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows

Include adult content

• Name: includeAdultContent
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies, TV Shows

Minimum automatic collection size

• Name: autoCollectionThreshold
• Value:
  0 - (Default) Disabled
  1 - 1
  2 - 2
  3 - 3
  4 - 4
• Library Type: Movies

Ratings Source

• Name: ratingsSource
• Value:
  rottentomatoes - (Default) Rotten Tomatoes
  imdb - IMDb
  themoviedb - The Movie Database
• Library Type: Movies

Enable video preview thumbnails

• Name: enableBIFGeneration
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies, TV Shows, Photos, Other Videos

Collections

• Name: collectionMode
• Value:
  0 - Disabled
  1 - Hide items which are in collections
  2 - (Default) Show collections and their items
• Library Type: Movies, TV Shows, Other Videos

Episode sorting

• Name: episodeSort
• Value:
  -1 - (Default) Library default
  0 - Oldest first
  1 - Newest first
• Library Type: TV Shows

Episode ordering

• Name: showOrdering
• Value:
  tmdbAiring - (Default) The Movie Database
  aired - TheTVDB
• Library Type: TV Shows

Use season titles

• Name: useSeasonTitles
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: TV Shows

Seasons

• Name: flattenSeasons
• Value:
  0 - (Default) Show
  1 - Hide
  2 - Hide for single-season series
• Library Type: TV Shows

Album sorting

• Name: albumSort
• Value:
  -1 - (Default) Library default
  0 - Oldest first
  1 - Newest first
  2 - By name
• Library Type: Music

Store track progress

• Name: enableTrackOffsets
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Music

Include related content from shared libraries

• Name: augmentWithSharedContent
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Music

Artist Bios

• Name: artistBios
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Music

Album Reviews and Critic Ratings

• Name: albumReviews
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Music

Popular Tracks

• Name: popularTracks
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Music

Genres

• Name: genres
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Music

Album Artist

• Name: albumPosters
• Value:
  1 - (Default) Both Plex Music and Local Files
  2 - Plex Music Only
  3 - Local Files Only
• Library Type: Music

Plex Movie (Legacy) Preferences

If you select Plex Movie (Legacy) as the movie agent, there are some additional preferences that can be set for that agent.

The preferences for this agent are listed below.

Localized titles

• Name: title
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies

Find trailers and extras automatically (Plex Pass required)

• Name: extras
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies

Skip extras which aren't trailers

• Name: only_trailers
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies

Use red band (restricted audiences) trailers when available

• Name: redband
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies

To set the above preferences, a second API request will need to be sent to the Plex server. This request is as follows:

GET http://{ip_address}:32400/:/plugins/com.plexapp.agents.imdb/prefs/set?title=[Value]&extras=[Value]&only_trailers=[Value]&redband=[Value]&X-Plex-Token={plex_token}

The Movie Database Settings

There are additional preferences that can be specified when using The Movie Database agent. These setting are listed below.

Use collection info from The Movie Database

• Name: collections
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies

Prefer artwork based on library language

• Name: localart
• Value:
  0 - Unchecked
  1 - (Default) Checked
• Library Type: Movies

Include adult content

• Name: adult
• Value:
  0 - (Default) Unchecked
  1 - Checked
• Library Type: Movies

Country

• Name: country
• Value:
  A value from the below table.
• Library Type: Movies

To set The Movie Database preferences, a second API request will need to be sent to the Plex server. This request is as follows:

GET http://{ip_address}:32400/:/plugins/com.plexapp.agents.themoviedb/prefs/set?collections=[Value]&localart=[Value]&adult=[Value]&country=[Value]&X-Plex-Token={plex_token}

Examples

curl -X POST http://{ip_address}:32400/library/sections?name={name}&type={type}&agent={agent}&scanner={scanner}&language={language}&location={media_location}&{preferences}&X-Plex-Token={plex_token}

import requests
plex_url = http://{ip_address}:32400/library/sections?name={name}&type={type}&agent={agent}&scanner={scanner}&language={language}&location={media_location}&{preferences}&X-Plex-Token={plex_token}
response = requests.post(plex_url)
print(response.text)

$response = Invoke-RestMethod 'http://{ip_address}:32400/library/sections?name={name}&type={type}&agent={agent}&scanner={scanner}&language={language}&location={media_location}&{preferences}&X-Plex-Token={plex_token}' -Method 'POST'
Write-Output $response