Items API

Query, filter, and search media items in the Jellyfin library

The Items API provides comprehensive access to media items in your Jellyfin library, including powerful filtering, searching, and sorting capabilities.

Get Items

Retrieve items based on a flexible query with extensive filtering options.

cURL

curl -X GET "https://your-server/Items" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json"

Endpoint

method · string · required

GET

endpoint · string · required

/Items

Query Parameters

userId · string (GUID)

The user ID. Required when not using an API key.

startIndex · integer

The record index to start at. All items with a lower index will be dropped from the results.

limit · integer

The maximum number of records to return.

recursive · boolean

When searching within folders, determines whether the search will be recursive.

searchTerm · string

Filter based on a search term.

sortBy · string[]

Comma-delimited sort orders. Options: Album, AlbumArtist, Artist, Budget, CommunityRating, CriticRating, DateCreated, DatePlayed, PlayCount, PremiereDate, ProductionYear, SortName, Random, Revenue, Runtime.

sortOrder · string[]

Sort order: Ascending, Descending. Comma-delimited.

parentId · string (GUID)

Specify this to localize the search to a specific item or folder. Omit to use the root.

fields · string[]

Comma-delimited additional fields: Budget, Chapters, DateCreated, Genres, HomePageUrl, IndexOptions, MediaStreams, Overview, ParentId, Path, People, ProviderIds, PrimaryImageAspectRatio, Revenue, SortName, Studios, Taglines.

includeItemTypes · string[]

Filter by item type. Comma-delimited. Examples: Movie, Series, Episode, MusicAlbum, Audio, Book.

excludeItemTypes · string[]

Exclude specific item types. Comma-delimited.

filters · string[]

Additional filters. Comma-delimited. Options: IsFolder, IsNotFolder, IsUnplayed, IsPlayed, IsFavorite, IsResumable, Likes, Dislikes.

isFavorite · boolean

Filter by items marked as favorite.

mediaTypes · string[]

Filter by MediaType. Comma-delimited. Options: Video, Audio, Photo, Book.

genres · string[]

Filter by genre. Pipe-delimited.

years · integer[]

Filter by production year. Comma-delimited.

tags · string[]

Filter by tag. Pipe-delimited.

officialRatings · string[]

Filter by official rating (PG, PG-13, TV-MA, etc). Pipe-delimited.

minCommunityRating · number

Filter by minimum community rating.

minCriticRating · number

Filter by minimum critic rating.

minPremiereDate · string (ISO 8601)

The minimum premiere date.

maxPremiereDate · string (ISO 8601)

The maximum premiere date.

hasThemeSong · boolean

Filter by items with theme songs.

hasThemeVideo · boolean

Filter by items with theme videos.

hasSubtitles · boolean

Filter by items with subtitles.

hasTrailer · boolean

Filter by items with trailers.

isHd · boolean

Filter by items that are HD.

is4K · boolean

Filter by items that are 4K.

is3D · boolean

Filter by items that are 3D.

isPlayed · boolean

Filter by items that have been played.

enableUserData · boolean · default: "true"

Include user data in the response.

enableImages · boolean · default: "true"

Include image information in output.

enableTotalRecordCount · boolean · default: "true"

Enable the total record count.

Response

Items · array

Array of BaseItemDto objects representing the media items.

Show BaseItemDto properties

Id · string (GUID)

Unique identifier for the item.

Name · string

The name of the item.

Type · string

The type of item (Movie, Series, Episode, etc).

Path · string

The file system path to the item.

Overview · string

The item description/overview.

Genres · string[]

Array of genre names.

ProductionYear · integer

Year the item was produced.

CommunityRating · number

Community rating score.

RunTimeTicks · integer

Runtime in ticks (10,000 ticks = 1 millisecond).

UserData · object

User-specific data for this item.

TotalRecordCount · integer

Total number of items matching the query.

StartIndex · integer

The starting index of the results.

Response Codes

• 200 - Success: Items returned
• 400 - Bad Request: userId is required when not using API key
• 401 - Unauthorized: User does not have permission to access the library
• 404 - Not Found: Library or parent item not found

---

Get Resume Items

Get items that can be resumed for a user.

cURL

curl -X GET "https://your-server/UserItems/Resume?userId=USER_ID&limit=10" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

GET /UserItems/Resume

Query Parameters

userId · string (GUID)

The user ID.

startIndex · integer

The record index to start at.

limit · integer

The maximum number of records to return.

parentId · string (GUID)

Specify this to localize the search to a specific item or folder.

excludeActiveSessions · boolean · default: "false"

Whether to exclude currently active sessions.

Response Codes

• 200 - Success: Resume items returned
• 404 - Not Found: User not found

---

Get/Update Item User Data

Manage user-specific data for an item (play count, favorite status, etc).

Get Item User Data

Get

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

GET /UserItems/{itemId}/UserData

Update Item User Data

Update

curl -X POST "https://your-server/UserItems/{itemId}/UserData" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "IsFavorite": true,
    "Played": true,
    "PlaybackPositionTicks": 0
  }'

POST /UserItems/{itemId}/UserData

Request Body (Update)

IsFavorite · boolean

Whether the item is marked as favorite.

Played · boolean

Whether the item has been played.

PlaybackPositionTicks · integer

Playback position in ticks.

PlayCount · integer

Number of times played.

Rating · number

User rating (likes/dislikes).

Response

PlaybackPositionTicks · integer

Current playback position.

PlayCount · integer

Number of times the item has been played.

IsFavorite · boolean

Whether marked as favorite.

Played · boolean

Whether the item has been played.

LastPlayedDate · string (ISO 8601)

Date the item was last played.

Response Codes

• 200 - Success: User data returned/updated
• 403 - Forbidden: User not allowed to view/update this data
• 404 - Not Found: Item or user not found