Metadata API

Fetch and update media metadata, search external providers, and refresh metadata

The Metadata API provides endpoints for managing item metadata, including fetching from external providers, updating metadata fields, and triggering metadata refreshes.

Refresh Item Metadata

Trigger a metadata refresh for a specific item.

cURL

curl -X POST "https://your-server/Items/{itemId}/Refresh?metadataRefreshMode=FullRefresh&imageRefreshMode=FullRefresh" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

method · string · required

POST

endpoint · string · required

/Items/{itemId}/Refresh

Path Parameters

itemId · string (GUID) · required

The item ID to refresh.

Query Parameters

metadataRefreshMode · string · default: "None"

Metadata refresh mode: None, ValidationOnly, Default, FullRefresh.

imageRefreshMode · string · default: "None"

Image refresh mode: None, ValidationOnly, Default, FullRefresh.

replaceAllMetadata · boolean · default: "false"

Whether to replace all metadata. Only applicable if mode is FullRefresh.

replaceAllImages · boolean · default: "false"

Whether to replace all images. Only applicable if mode is FullRefresh.

regenerateTrickplay · boolean · default: "false"

Whether to regenerate trickplay images. Only applicable if mode is FullRefresh.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Metadata refresh queued successfully
• 404 - Not Found: Item not found

---

Update Item Metadata

Update metadata fields for an item.

cURL

curl -X POST "https://your-server/Items/{itemId}" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Updated Movie Title",
    "Overview": "Updated description",
    "Genres": ["Action", "Thriller"],
    "CommunityRating": 8.5,
    "ProductionYear": 2024,
    "ProviderIds": {
      "Tmdb": "12345",
      "Imdb": "tt1234567"
    }
  }'

Endpoint

POST /Items/{itemId}

Path Parameters

itemId · string (GUID) · required

The item ID.

Request Body

Name · string

Item name/title.

OriginalTitle · string

Original title in source language.

ForcedSortName · string

Forced sort name for custom ordering.

Overview · string

Item description/plot summary.

Tagline · string

Short tagline.

Genres · string[]

Array of genre names.

Tags · string[]

Array of custom tags.

Studios · object[]

Array of studio objects with Name property.

ProductionYear · integer

Year of production.

PremiereDate · string (ISO 8601)

Date the item premiered.

EndDate · string (ISO 8601)

End date (for series).

CommunityRating · number

Community rating (0-10).

CriticRating · number

Critic rating.

OfficialRating · string

Official content rating (PG, PG-13, etc).

CustomRating · string

Custom rating.

ProviderIds · object

External provider IDs (Tmdb, Imdb, Tvdb, etc).

People · object[]

Array of person objects with Name, Role, and Type properties.

LockData · boolean

Whether metadata is locked from changes.

LockedFields · string[]

Specific metadata fields that are locked.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Item updated successfully
• 404 - Not Found: Item not found

---

Get Metadata Editor Info

Retrieve metadata editor information for an item.

cURL

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

Endpoint

GET /Items/{itemId}/MetadataEditor

Path Parameters

itemId · string (GUID) · required

The item ID.

Response

ParentalRatingOptions · array

Available parental rating options.

Countries · array

Available country options.

Cultures · array

Available culture/language options.

ExternalIdInfos · array

External ID provider information.

Show ExternalIdInfo properties

Name · string

Provider name (TMDb, IMDb, etc).

Key · string

Provider key.

Type · string

Type of external ID.

UrlFormatString · string

URL format for the provider.

ContentType · string

Current content type.

ContentTypeOptions · array

Available content type options.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 200 - Success: Metadata editor info returned
• 404 - Not Found: Item not found

---

Remote Search

Search external metadata providers for media information.

Search Movies

Movie

curl -X POST "https://your-server/Items/RemoteSearch/Movie" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SearchInfo": {
      "Name": "The Matrix",
      "Year": 1999
    }
  }'

POST /Items/RemoteSearch/Movie

Search Series

Series

curl -X POST "https://your-server/Items/RemoteSearch/Series" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SearchInfo": {
      "Name": "Breaking Bad",
      "Year": 2008
    }
  }'

POST /Items/RemoteSearch/Series

Search Music Album

Album

curl -X POST "https://your-server/Items/RemoteSearch/MusicAlbum" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SearchInfo": {
      "Name": "Abbey Road",
      "Artists": ["The Beatles"],
      "Year": 1969
    }
  }'

POST /Items/RemoteSearch/MusicAlbum

Other available endpoints:

• /Items/RemoteSearch/Trailer
• /Items/RemoteSearch/MusicVideo
• /Items/RemoteSearch/MusicArtist
• /Items/RemoteSearch/BoxSet
• /Items/RemoteSearch/Book
• /Items/RemoteSearch/Person

Request Body

SearchInfo · object · required

Search criteria object.

Show SearchInfo properties

Name · string

Name/title to search for.

Year · integer

Production/release year.

ProviderIds · object

Known provider IDs to match.

Artists · string[]

Artist names (for music).

ItemId · string (GUID)

Optional existing item ID.

SearchProviderName · string

Specific provider to search.

IncludeDisabledProviders · boolean

Include disabled providers in search.

Response

SearchResults · array

Array of search result objects.

Show RemoteSearchResult properties

Name · string

Result name/title.

ProductionYear · integer

Production year.

ProviderIds · object

External provider IDs.

Overview · string

Description.

ImageUrl · string

URL to poster/cover image.

SearchProviderName · string

Provider that returned this result.

Response Codes

• 200 - Success: Search results returned

---

Apply Search Result

Apply a remote search result to an item and refresh metadata.

cURL

curl -X POST "https://your-server/Items/RemoteSearch/Apply/{itemId}?replaceAllImages=true" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "The Matrix",
    "ProductionYear": 1999,
    "ProviderIds": {
      "Tmdb": "603",
      "Imdb": "tt0133093"
    },
    "ImageUrl": "https://..."
  }'

Endpoint

POST /Items/RemoteSearch/Apply/{itemId}

Path Parameters

itemId · string (GUID) · required

The item ID to update.

Query Parameters

replaceAllImages · boolean · default: "true"

Whether to replace all existing images.

Request Body

RemoteSearchResult object from search results.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Search result applied and metadata refreshed
• 404 - Not Found: Item not found

---

Get External ID Info

Retrieve external ID information for an item.

cURL

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

Endpoint

GET /Items/{itemId}/ExternalIdInfos

Path Parameters

itemId · string (GUID) · required

The item ID.

Response

Array of ExternalIdInfo objects describing available external ID providers.

ExternalIdInfos · array

Show ExternalIdInfo properties

Name · string

Display name of the provider.

Key · string

Unique key for the provider.

Type · string

Type of external ID.

UrlFormatString · string

URL format string with placeholder for the ID.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 200 - Success: External ID info returned
• 404 - Not Found: Item not found

---

Update Content Type

Update the content type for an item.

cURL

curl -X POST "https://your-server/Items/{itemId}/ContentType?contentType=movies" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Endpoint

POST /Items/{itemId}/ContentType

Path Parameters

itemId · string (GUID) · required

The item ID.

Query Parameters

contentType · string

Content type: movies, tvshows, music, books, homevideos, musicvideos, photos, or empty for inherit.

Authorization

Requires elevation policy (administrator access).

Response Codes

• 204 - No Content: Content type updated
• 404 - Not Found: Item not found

---

Library Options

Manage metadata options for libraries.

Get Library Options Info

Get

curl -X GET "https://your-server/Libraries/AvailableOptions?libraryContentType=movies" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

GET /Libraries/AvailableOptions

Query Parameters

libraryContentType · string

Library content type to get options for.

isNewLibrary · boolean · default: "false"

Whether this is for a new library.

Response

MetadataFetchers · array

Available metadata fetcher plugins per item type.

ImageFetchers · array

Available image fetcher plugins per item type.

MetadataSavers · array

Available metadata saver plugins.

MetadataReaders · array

Available local metadata reader plugins.

SubtitleFetchers · array

Available subtitle fetcher plugins.

TypeOptions · array

Options organized by item type.

Authorization

Requires first-time setup or default policy.

Response Codes

• 200 - Success: Library options returned