Skip to main content
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 -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.
​
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