Library API

Manage libraries, scan media, and perform library operations

The Library API provides endpoints for managing Jellyfin libraries, including scanning, refreshing, deleting items, and retrieving library information.

Start Library Scan

Initiate a full library scan to refresh all media.

cURL

curl -X POST "https://your-server/Library/Refresh" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

method · string · required

POST

endpoint · string · required

/Library/Refresh

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Library scan started successfully

---

Delete Items

Delete one or more items from the library and filesystem.

Delete Single Item

Single Item

curl -X DELETE "https://your-server/Items/{itemId}" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

DELETE /Items/{itemId}

Delete Multiple Items

Multiple Items

curl -X DELETE "https://your-server/Items?ids=id1,id2,id3" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

DELETE /Items

Path Parameters

itemId · string (GUID) · required

The item ID to delete (single item endpoint).

Query Parameters

ids · string[] · required

Comma-delimited item IDs to delete (multiple items endpoint).

Response Codes

• 204 - No Content: Item(s) deleted successfully
• 401 - Unauthorized: User does not have permission to delete
• 404 - Not Found: Item not found

---

Get Item Counts

Retrieve item counts for various media types.

cURL

curl -X GET "https://your-server/Items/Counts?userId=USER_ID" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/Counts

Query Parameters

userId · string (GUID)

Get counts from a specific user’s library.

isFavorite · boolean

Get counts of favorite items only.

Response

MovieCount · integer

Number of movies in the library.

SeriesCount · integer

Number of TV series.

EpisodeCount · integer

Number of episodes.

AlbumCount · integer

Number of music albums.

SongCount · integer

Number of audio tracks.

MusicVideoCount · integer

Number of music videos.

BoxSetCount · integer

Number of box sets.

BookCount · integer

Number of books.

Response Codes

• 200 - Success: Item counts returned

---

Get Media Folders

Retrieve all user media folders (libraries).

cURL

curl -X GET "https://your-server/Library/MediaFolders" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Library/MediaFolders

Query Parameters

isHidden · boolean

Filter by folders that are marked hidden.

Response

Items · array

Array of media folder objects.

Show Media Folder properties

Id · string (GUID)

Unique identifier for the folder.

Name · string

The folder name.

CollectionType · string

Type of collection (movies, tvshows, music, etc).

Path · string

File system path to the folder.

IsHidden · boolean

Whether the folder is hidden.

TotalRecordCount · integer

Total number of media folders.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 200 - Success: Media folders returned

---

Get Physical Paths

Get a list of physical paths from virtual folders.

cURL

curl -X GET "https://your-server/Library/PhysicalPaths" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Library/PhysicalPaths

Response

Array of physical path strings.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 200 - Success: Physical paths returned

---

Get Item Ancestors

Retrieve all parent items of a specific item.

cURL

curl -X GET "https://your-server/Items/{itemId}/Ancestors?userId=USER_ID" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/{itemId}/Ancestors

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

userId · string (GUID)

Filter by user ID and attach user data.

Response

Array of BaseItemDto objects representing the parent items, from immediate parent to root.

Response Codes

• 200 - Success: Item ancestors returned
• 404 - Not Found: Item not found

---

Get Similar Items

Find items similar to a specific item.

cURL

curl -X GET "https://your-server/Items/{itemId}/Similar?limit=10" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /Items/{itemId}/Similar

Also available at:

• /Movies/{itemId}/Similar
• /Shows/{itemId}/Similar
• /Albums/{itemId}/Similar
• /Artists/{itemId}/Similar

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

userId · string (GUID)

Filter by user ID and attach user data.

limit · integer

Maximum number of similar items to return.

fields · string[]

Comma-delimited additional fields to return.

excludeArtistIds · string[]

Comma-delimited artist IDs to exclude.

Response

Items · array

Array of similar items.

TotalRecordCount · integer

Total number of similar items found.

Response Codes

• 200 - Success: Similar items returned

---

Download Item

Download the original media file for an item.

cURL

curl -X GET "https://your-server/Items/{itemId}/Download" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -o "downloaded-file.mp4"

Endpoint

GET /Items/{itemId}/Download

Path Parameters

itemId · string (GUID) · required

The item ID.

Authorization

Requires download policy permission.

Response

The media file stream with appropriate content type and filename.

Response Codes

• 200 - Success: Media file stream returned
• 404 - Not Found: Item not found
• 400 - Bad Request: Item does not support downloading

---

Get Theme Media

Retrieve theme songs and videos for an item.

Get Theme Songs

Theme Songs

curl -X GET "https://your-server/Items/{itemId}/ThemeSongs" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Items/{itemId}/ThemeSongs

Get Theme Videos

Theme Videos

curl -X GET "https://your-server/Items/{itemId}/ThemeVideos" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Items/{itemId}/ThemeVideos

Get All Theme Media

All Theme Media

curl -X GET "https://your-server/Items/{itemId}/ThemeMedia" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Items/{itemId}/ThemeMedia

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

userId · string (GUID)

Filter by user ID and attach user data.

inheritFromParent · boolean · default: "false"

Whether to search parent items for theme media.

Response

Items · array

Array of theme media items.

TotalRecordCount · integer

Total number of theme items.

OwnerId · string (GUID)

ID of the item that owns the theme media.

Response Codes

• 200 - Success: Theme media returned
• 404 - Not Found: Item not found

---

Virtual Folders

Manage virtual folders (libraries).

Get Virtual Folders

Get

curl -X GET "https://your-server/Library/VirtualFolders" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Library/VirtualFolders

Add Virtual Folder

Add

curl -X POST "https://your-server/Library/VirtualFolders?name=Movies&collectionType=movies" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "LibraryOptions": {
      "PathInfos": [{"Path": "/media/movies"}],
      "EnableRealtimeMonitor": true
    }
  }'

POST /Library/VirtualFolders

Remove Virtual Folder

Remove

curl -X DELETE "https://your-server/Library/VirtualFolders?name=Movies" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

DELETE /Library/VirtualFolders

Authorization

Requires first-time setup or elevation policy.

Response Codes

• 200 - Success: Virtual folders returned (GET)
• 204 - No Content: Operation completed successfully (POST/DELETE)
• 404 - Not Found: Virtual folder not found (DELETE)