API reference

Who performed an audited action.

object

• apiKeyIdstring

  ID of the API key that performed the action; present when the actor kind is "apiKey".

• kindActivityActorKindRequired
• namestring

  Display name of the actor, captured at the time the entry was recorded.

• pluginIdstring

  ID of the plugin that performed the action; present when the actor kind is "plugin".

• userIdstring

  ID of the member that performed the action; present when the actor kind is "member".

Kind of actor behind an activity entry: "system" for the server itself (scheduled or automatic work), "member" for a signed-in account, "apiKey" for a request authenticated with an API key, "plugin" for an installed plugin.

string: system | member | apiKey | plugin

Category of an activity entry: "content" for edits to items and metadata, "deletion" for removals, "externalTool" for actions by external tools, "settings" for configuration changes, "security" for authentication and access changes.

string: content | deletion | externalTool | settings | security

One record in the activity log.

object

• actionstringRequired

  Action in the form "target.verb", for example "item.delete" or "missing.confirm".

• actorActivityActorRequired
• atstring (date-time)Required

  Time the action happened, in RFC 3339 format (UTC).

• categoryActivityCategoryRequired
• detailsobject

  Structured details such as field names and paths. Never contains field contents or secrets.

• idstringRequired

  Unique ID of the activity entry.

• remoteAddrstring

  Network address the request came from.

• targetActivityTargetRequired

One page of activity log entries.

object

• entriesarray of ActivityEntryRequired

  Entries on this page.

• nextCursorstring

  Cursor to pass to fetch the next page. Omitted when there is no further page.

The object an audited action was applied to.

object

• idstring

  ID of the target object.

• kindstringRequired

  Kind of target object (see ActivityTargetKind). Empty string for actions that have no target.

• namestring

  Name of the target object, captured at the time the entry was recorded.

Kind of object an activity entry refers to: "item" (media item), "library", "person", "user" (member account), "plugin", "apiKey", "server" (server-wide settings), "schedule" (scheduled task), "backup".

string: item | library | person | user | plugin | apiKey | server | schedule | backup

One extra attribute of an item or person: a provider value that has no dedicated field, shown for display only.

object

• keystringRequired

  Lower-case snake_case key, for example "label" or "height_cm".

• labelstring

  Display name declared by an enabled plugin for keys that have no built-in translation, in the requested language. Omitted when there is none.

• valuestringRequired

  Text to display.

Disk usage of one server cache.

object

• clearablebooleanRequired

  True if the cache can be emptied with POST /system/caches/{name}/clear. Currently only the "remote-images" cache, and only when the server has its dedicated original-image cache attached.

• fileCountinteger (int64)Required

  Number of files in the cache at the last measurement.

• measuredAtstring (date-time)Required

  Time the most recent measurement finished, in RFC 3339 format. Null while the status is "pending".

• namestringRequired

  Cache name, for example "images" or "subtitles".

• pathstringRequired

  Directory on the server where the cache is stored.

• sizeBytesinteger (int64)Required

  Total size of the cache in bytes at the last measurement.

• statusstring: ok | error | pendingRequired

  Measurement status: "ok" if the last measurement succeeded, "error" if it failed (for example the directory is unreadable or the measurement timed out), "pending" if the first measurement has not finished. With "error" or "pending", sizeBytes and fileCount are 0.

Request body for creating a media library.

object

• accessUserIdsarray of string

  IDs of members who get access to the library on creation. If omitted or empty, only administrators can see it. An ID that does not exist or belongs to a disabled user returns 400.

• collectionTypeLibraryKindRequired
• namestringRequired

  Display name of the library.

• optionsLibraryOptionsUpdate

  Complete library settings applied at creation, with the same fields as PUT /libraries/{id}/options (remoteAllowedHosts is required). The operation is atomic: an invalid field returns 400 and nothing is created, and if saving the settings fails the new library is removed. If both realtimeMonitor and options.realtimeMonitor are set, the latter wins.

• pathsarray of stringRequired

  Absolute directory paths that make up the library.

• realtimeMonitorboolean

  Whether to watch the library for file changes as they happen. Defaults to true. See LibraryOptions.realtimeMonitor.

A page of item summaries using cursor pagination.

object

• itemsarray of ItemSummaryRequired

  Items on this page.

• nextCursorstring

  Cursor for the next page. Null on the last page.

• totalCountinteger

  Total number of items matching the filters. Present only when the request sets includeTotal=true.

A client device that has signed in to the server.

object

• clientstringRequired

  Name of the client application.

• countsTowardLimitbooleanRequired

  Whether this device counts toward the plan's device limit, taken from the license's device ranking; the number of rows marked true equals the license page's device usage. Devices that do not count are still listed, with the reason in notCountedReason (over-limit devices use overLimit).

• devicestringRequired

  Name of the device.

• idstringRequired

  Public identifier of the device (an irreversible hash of its token).

• kindstring: player | web | appRequired

  "player" for a sign-in from a third-party player (token), "web" for a sign-in from a web browser.

• lastSeenstring (date-time)Required

  Time the device was last active, in RFC 3339 format (UTC).

• loginCountinteger

  How many sign-ins were merged into this row (sign-ins sharing a device ID or browser ID form one row; a sign-in without an identifier counts as its own device and has 1).

• notCountedReasonstring: memberDisabled | notPlayed

  Why the device does not count when it is not over the limit: "memberDisabled" when every member signed in on it is disabled, "notPlayed" for a web sign-in that never played anything. Omitted when the device counts or is over the limit.

• overLimitbooleanRequired

  True when the device is beyond the plan's device limit. The earliest signed-in devices are kept; new playback on this device is refused with "plan_device_limit" until earlier devices sign out. False when there is no license information or no limit is exceeded.

• userIdstringRequired

  ID of the member the device is signed in as.

• userNamestring

  Name of the member the device is signed in as.

• usersarray of NamedRef

  Members signed in on this device, most recently active first.

• versionstring

  Version of the client application.

Machine-readable error code returned in ErrorResponse.code. Clients should branch on the code rather than the message. Some codes carry extra values in the response params (for example field, limit, pluginId, libraryId, reason, retryAfterSeconds). Common codes: "bad_request" (400), "unauthorized" (401: missing, invalid or expired credentials or API key), "forbidden" and "admin_only" (403), "not_found" (404), "conflict" (409), "too_large" (413, params.maxBytes), "too_many_requests" (429, Retry-After header gives seconds to wait), "internal_error" (500), "service_unavailable" and "not_enabled" (503). Validation codes (400): "field_required", "field_invalid", "field_too_long", "path_not_absolute", "host_invalid", "unsupported_language", "public_url_invalid", "discovery_url_invalid", "password_rule", "schedule_" (invalid schedule rule), "backup_" (invalid backup settings, or wrong password for a backup). Other codes cover login ("invalid_credentials", "wrong_pin", "wrong_password", "pin_locked", "password_required", "setup_done"), plugins ("plugin_", "recognizer_not_installed", "provider_not_installed", "image_source_not_installed", "segment_provider_not_installed", "no_person_provider", "no_scrape_provider"), library and metadata operations ("library_", "subtitle_", "writeback_replace_confirm", "nfo_write_disabled", "no_provider_id", "id_owned_by_other", "split_ids_conflict", "item_count_changed", "merge_chain", "last_admin"), playback and casting ("cast_disabled", "cast_not_possible", "hls_busy", "parental_time", "session_not_stoppable"), import ("source_unreachable", "source_unauthorized", "import_source_kind_mismatch"), and licensing and plan limits ("license_", "plan_*").

string: bad_request | unauthorized | forbidden | forbidden_origin | not_found | conflict | too_large | too_many_requests | internal_error | service_unavailable | not_enabled | invalid_credentials | wrong_pin | wrong_password | pin_locked | password_required | setup_done | plugin_needs_configuration | plugin_rate_limited | plugin_builtin | plugin_config_rejected | no_person_provider | no_scrape_provider | no_provider_id | nfo_write_disabled | item_count_changed | scrape_not_cancellable | no_posters | source_unreachable | source_unauthorized | id_owned_by_other | split_ids_conflict | provider_error | invalid_id | unsupported_language | library_delete_blocked | last_admin | merge_chain | admin_only | session_not_stoppable | schedule_trigger_not_allowed | schedule_cron_invalid | schedule_interval_out_of_range | schedule_window_invalid | schedule_rule_invalid | schedule_runner_unavailable | log_retention_invalid | backup_in_progress | backup_restore_pending | backup_password_invalid | backup_wrong_password | backup_too_new | backup_dir_invalid | backup_keep_invalid | update_check_disabled | import_source_kind_mismatch | fonts_loading | hls_busy | public_url_invalid | field_required | field_invalid | field_too_long | path_not_absolute | host_invalid | library_no_providers | writeback_replace_confirm | cast_disabled | cast_not_possible | cast_renderer_failed | cast_session_ended | recognizer_not_installed | provider_not_installed | discovery_url_invalid | segment_provider_not_installed | license_invalid | license_seats_full | license_unavailable | license_unbind_limit | license_rate_limited | license_expired | license_trial_used | trial_used_on_server | license_trial_closed | plan_admin_only | plan_member_limit | plan_device_limit | plan_stream_limit | password_rule | license_required | parental_time | library_not_writable | subtitle_not_downloadable | subtitle_provider_failed | image_source_not_installed | segment_detect_disabled | regex_invalid | cleanup_changed | cleanup_too_slow | cleanup_too_many | library_path_not_allowed | unsupported_media_type | check_running | check_cooldown | check_busy | plugin_not_running

Standard error body returned for failed requests.

object

• codeErrorCodeRequired
• messagestringRequired

  Human-readable explanation in the server's default language. Intended for logs and developers; branch on code instead.

• paramsobject

  Extra values that go with the error code (numbers, names, fields). See ErrorCode. Omitted when the code has no parameters.

Type of a bonus item: "Trailer", "BehindTheScenes", "DeletedScene", "Featurette", "Interview", "Scene", "Short", "Clip", "Other", or "AdditionalPart". Main features do not carry this field. "AdditionalPart" marks the second and later segments of a multi-part video (-cd2, -cd3 and so on); it is not a bonus item, its indexNumber in the item detail is the part number (starting at 2), and like bonus items it is hidden from item lists by default.

string: Trailer | BehindTheScenes | DeletedScene | Featurette | Interview | Scene | Short | Clip | Other | AdditionalPart

A crop suggestion as an aspect ratio plus a position, for when the original size is not known up front.

object

• aspectnumber (double)Required

  Wanted width divided by height.

• xnumber (double)Required

  Horizontal position of the crop frame, like CSS object-position (0 left, 0.5 center, 1 right).

• ynumber (double)Required

  Vertical position of the crop frame (0 top, 0.5 center, 1 bottom).

A crop region as fractions (0 to 1) of the original image width and height.

object

• heightnumber (double)Required

  Height of the region.

• widthnumber (double)Required

  Width of the region.

• xnumber (double)Required

  Left edge of the region.

• ynumber (double)Required

  Top edge of the region.

Crop information for one image, for drawing a crop frame. The image the tag refers to is already cropped.

object

• cropImageCropRect
• cropHintImageCropHint

  Crop suggestion given by the provider as aspect ratio and position. Omitted when there is none. The crop wins when both are set.

• cropManualboolean

  True when the crop or focus was set by an administrator. Present only when true.

• effectiveCropImageCropRect

  The crop actually applied; the crop when set, otherwise the crop hint resolved against the original size. Omitted when not known or not needed.

• focusImageFocusPoint
• heightinteger

  Height of the original image in pixels. Omitted when not known yet.

• indexintegerRequired

  Index among images of the same kind, starting at 0.

• kindImageKindRequired
• tagstringRequired

  Tag of the image.

• widthinteger

  Width of the original image in pixels. Omitted when not known yet.

A focus point as fractions (0 to 1) of the original image width and height, for example the center of a face.

object

• xnumber (double)Required

  Horizontal position.

• ynumber (double)Required

  Vertical position.

Kind of image an item can have: "primary" (poster or main image), "backdrop" (background), "logo", "thumb", "banner", "art", "disc".

string: primary | backdrop | logo | thumb | banner | art | disc | photo | still

Tags identifying the images an item has, one field per image kind. A kind the item has no image for is omitted.

object

• backdropstring

  Tag of the backdrop image. An item has at most one; additional stills are listed in ItemDetail.stills.

• logostring

  Tag of the logo image.

• primarystring

  Tag of the primary (poster) image.

• thumbstring

  Tag of the thumbnail image.

A plugin installed on the server, with its state and settings.

object

• allowedPermissionsarray of stringRequired

  Permissions an administrator has allowed for this plugin. A plugin can use a permission only when it declares it and it is listed here. Empty when none.

• attributionPluginAttributionRequired
• authorstring

  Author of the plugin. Taken from the plugin catalog entry when there is one, otherwise from what the plugin declares itself. Omitted when neither has it.

• authorSourcestring: catalog | plugin

  Where author and homepage come from: "catalog" (the plugin catalog entry) or "plugin" (declared by the plugin itself, not reviewed by a catalog). Omitted when neither has them.

• bundledbooleanRequired

  True for plugins shipped with the server image. Uninstalling the bundled version removes the plugin completely (it can be installed again from the catalog); uninstalling an update reverts to the bundled version.

• bundledVersionstring

  Version shipped with the server image. If version is newer, an update from the official catalog is installed and can be removed to revert to the bundled version.

• capabilitiesarray of stringRequired

  Capabilities the plugin declares, for example the kinds of metadata or other services it provides.

• catalogstringRequired

  URL of the plugin catalog it was installed from. Updates are only taken from the same catalog.

• concurrencyintegerRequired

  Effective maximum number of concurrent requests to the plugin.

• concurrencyOverrideinteger

  Concurrency limit set by an administrator. Omitted when not overridden.

• configuredbooleanRequired

  True when every required setting the plugin declares has a value. A plugin that is not configured can still be selected for a library; it only starts scraping once its settings are complete.

• descriptionstring

  Short description of the plugin.

• devboolean

  True when the plugin was loaded from the developer-mode directory on the server (unsigned, not from any catalog, never updated automatically).

• disableReasonstring: manual | crash | not_enabled

  Why the plugin is disabled: "manual" (an administrator disabled it), "crash" (it crashed too many times), "not_enabled" (a bundled plugin that was registered but never enabled, usually because it needs configuration first).

• enabledbooleanRequired

  Whether the plugin is enabled.

• extensionbooleanRequired

  True for a built-in extension, which runs inside the server process and is upgraded with it. It can only be enabled, disabled and configured, not uninstalled or updated on its own.

• featuresarray of stringRequired

  Codes of paid features the plugin declares it needs; empty when none. May be empty before the plugin has started for the first time.

• homepagestring (uri)

  Project home page of the plugin (https). Same source as author. Omitted when there is none.

• idstringRequired

  Unique plugin ID.

• installedAtstring (date-time)Required

  Time the plugin was installed, in RFC 3339 format (UTC).

• lastErrorstring

  Most recent error text reported by the plugin on start, crash, health check or configuration. Kept for older clients; prefer the error code.

• lastErrorCodeProviderErrorCode
• licenseRequiredbooleanRequired

  For a plugin, true when any entry of paidFeatures is not entitled; it can still be enabled, but the capabilities behind that feature are not used until the license covers it. For a built-in extension (extension is true), true when a declared feature is not covered; it cannot be enabled (enabling returns 403 "license_required").

• missingRequiredarray of stringRequired

  Keys of required settings that have no value. When non-empty, status is "needs_configuration".

• namestringRequired

  Display name of the plugin.

• needsAttentionbooleanRequired

  True if the plugin has a problem the administrator should look at - crashed and disabled, needs configuration, incompatible, or the upstream service rejected its credentials.

• officialbooleanRequired

  True for plugins published by the server vendor.

• paidFeaturesarray of PluginPaidFeatureRequired

  Paid features the plugin uses, derived by the server from the capabilities it declares and the features in its manifest, sorted by feature code. Empty when none, and always empty for a built-in extension.

• pausedUntilstring (date-time)

  Time until which the plugin is paused because it reported an upstream rate limit, in RFC 3339 format.

• permissionsarray of stringRequired

  Permissions the plugin declares in its manifest: "llm" (use the configured AI service) and "network.lan" (multicast and connections to devices on the local network, disclosure only). Empty when none.

• previousVersionstring

  Previously installed version that can be rolled back to.

• protocolintegerRequired

  Version of the plugin protocol the plugin was built for.

• statsarray of PluginStatRequired

  Runtime figures for the plugin; empty when there are none. Each code is stable and the client translates it: "calls" and "errors" (last 24 hours), "last-success" (unit "time"), "quota" (remaining allowance reported upstream). Plugin-specific codes are prefixed with the plugin ID; clients may skip codes they do not recognize.

• statusstring: unknown | disabled | crash_disabled | starting | running | needs_configuration | restarting | idle | incompatible | license_required | not_installedRequired

  Runtime status: "unknown", "disabled", "crash_disabled" (disabled after repeated crashes), "starting", "running", "needs_configuration" (enabled but required settings are missing), "restarting", "idle" (enabled and configured, process stopped for inactivity and started again on next use), "incompatible" (built for an older protocol and must be updated; not retried and not counted as a crash), "license_required" (paid plugin not covered by the current license; process is stopped, settings and data are kept, and it restarts when the license is restored), "not_installed" (the settings are kept but the plugin binary is gone, for example an official plugin that is no longer shipped with the image; installing it again from a catalog restores it and keeps the settings).

• tasksarray of PluginTask

  Scheduled tasks the plugin registered (only while it is enabled); omitted when it has none. Each can be run with POST /admin/schedules/{task}/run.

• updatedAtstring (date-time)Required

  Time the plugin was last updated, in RFC 3339 format (UTC).

• versionstringRequired

  Installed version of the plugin.

Overview attention category that GET /items can expand into a list: "needsIdentify", "scrapeFailed", "scrapePending", "noPoster", "unprobed", "missing" or "scrapeNotQueued".

string: needsIdentify | scrapeFailed | scrapePending | noPoster | unprobed | missing | scrapeNotQueued

Full details of a media item: everything in ItemSummary plus metadata, credits and media sources.

object

• communityRatingnumber

  Community rating of the item, typically on a 0-10 scale.

• dateCreatedstring (date-time)Required

  Time the item was first added to the library (UTC, RFC 3339).

• extraTypeExtraType
• hasPosterbooleanRequired

  True if the item has a poster image.

• idstringRequired

  Unique item ID.

• imageTagstring

  Short hash of the primary poster image; use it as the cache-busting tag when fetching the image.

• indexNumberinteger

  Episode number for an episode, season number for a season.

• libraryIdstringRequired

  ID of the library that contains the item.

• lockedboolean

  True if any metadata field is locked or the whole item is locked.

• mergedIntostring

  For a series that is a non-primary member of a merged group, the ID of the primary series. Omitted otherwise. Admin lists do not collapse merged series, so this marks them as merged.

• missingboolean

  True if the item's file is missing and the item is waiting to be cleaned up.

• namestringRequired

  Display title of the item.

• originalLanguagestring

  Original language of the work as a BCP 47 tag (for example "ja"). Omitted when unknown.

• originalTitlestring

  Title in the original language.

• parentIndexNumberinteger

  Season number an episode belongs to.

• productCodestring

  Product code of the item, for example "ABC-123". Omitted when there is none.

• productionYearinteger

  Year of production or first release.

• runtimeTicksinteger (int64)

  Runtime in ticks (1 tick = 100 nanoseconds).

• scrapeStateScrapeState
• seasonIdstring

  ID of the season an episode belongs to. Set only for episodes.

• seriesIdstring

  ID of the series a season or episode belongs to. Set only for seasons and episodes.

• sortNamestringRequired

  Name used for sorting.

• typeItemTypeRequired
• versionMemberCountinteger

  For a movie that is the primary entry of a version group, the number of other items merged into it. Omitted when nothing is merged.

• versionOfstring

  For a movie that is a member of a version group, the ID of the primary item. Omitted when the item is not a member. Admin lists do not collapse merged items.

• attributesarray of AttributeItem

  Extra attributes from the metadata provider (for display only, sorted by key). Omitted when there are none.

• creditsarray of PersonCreditRequired

  People credited on the item (cast and crew).

• endDatestring (date-time)

  Date a series ended.

• extrasarray of ItemSummary

  Local bonus items (trailers, behind-the-scenes, interviews and so on), excluding additional parts, ordered by index. Omitted when there are none. Each entry's extraType gives its kind.

• genresarray of stringRequired

  Genre names.

• imageDetailsarray of ImageDetail

  Crop information for each image, sorted by kind and index. Omitted when the item has no images.

• imagesImageTags
• mediaSourcesarray of MediaSourceRequired

  Playable versions of the item, each with its file and stream information.

• metadataStateMetadataState
• officialRatingstring

  Content rating label, for example "PG-13".

• overviewstring

  Plot summary of the item.

• partsarray of ItemSummary

  Additional segments of a multi-part video (the first segment is the item itself), ordered by part number. Omitted when there are none.

• premiereDatestring (date-time)

  Premiere or first air date.

• productionLocationsarray of string

  Countries or places where the item was produced.

• providerIdsobject

  Metadata provider IDs, keyed by lowercase provider name (for example "imdb", "tmdb").

• ratingsarray of ItemRating

  Ratings from individual sources. Omitted when there are none; communityRating is still provided separately.

• recognizedTagsarray of string

  Tags the name recognizer found in the file name (for example markers that cannot be measured from the file). Read-only; shown, filtered and matched by badge rules together with tags. Omitted when there are none.

• remoteTrailersarray of RemoteTrailer

  Remote trailers in order of preference. Omitted when there are none.

• seasonNamestring

  Name of the season an episode belongs to.

• seriesNamestring

  Name of the series a season or episode belongs to.

• stillsarray of ItemStill

  Still frames of the item in index order. Only filled in item details, omitted when there are none.

• studiosarray of stringRequired

  Studio names.

• subtitleDownloadBlockedReasonSubtitleDownloadBlockedReason
• subtitleDownloadableboolean

  Whether subtitles can be downloaded for the item: a subtitle provider is available, the video's directory is writable and the source is not remote read-only. Set only for movies and episodes.

• taglinestring

  Short tagline of the item.

• tagsarray of stringRequired

  Tags attached to the item.

• writeBackWarningstring: unavailable | conflict | failed

  Present only in the response of POST /items/{id}/identify. The metadata was applied but writing it back to disk failed: "unavailable" (read-only mount or insufficient permission), "conflict" (a user-owned file was found and left untouched), "failed" (any other reason; see server logs).

A rating of an item from one source.

object

• maxnumber (double)Required

  Maximum possible score. 10 when no value is recorded.

• sourcestringRequired

  Lowercase source code, for example "tmdb", "imdb", "douban".

• valuenumber (double)Required

  The score.

• votesinteger (int64)

  Number of votes. Omitted when the source does not provide it.

Field to sort items by. Items with a missing value sort last for date fields (premiereDate, year, datePlayed); numeric and rating fields (rating, criticRating, officialRating, runtime, playCount) treat missing as lowest, so they come first ascending and last descending. Ties are broken by name then ID, so results are reproducible. "lastContentAdded" is when a series or collection last gained content; "path" orders by file name; "played" and "favorite" use the current user's state (true first); "officialRating" orders by rating level (G, PG, PG-13, R...) rather than as text; "seriesDatePlayed" is when a series was last played (series only); "size" and "resolution" use the primary version's file size and pixel count; "container" and "studio" use the primary version's container and the first studio (empty is lowest); "productCode" uses the normalized product code, ignoring case and full-width characters, and items without one are lowest; "childCount" uses the child count (visible members for a collection) and returns 400 if unsupported. When listing only collections (type=BoxSet), "dateAdded" is the time the newest member was added.

string: name | dateAdded | premiereDate | year | rating | runtime | datePlayed | playCount | index | random | criticRating | officialRating | dateModified | lastContentAdded | seriesName | path | played | favorite | seriesDatePlayed | size | container | resolution | studio | productCode | childCount

State that needs attention on an item: "unidentified" (awaiting identification or scraping failed), "noPoster" (no primary image), "noMetadata" (no overview and no provider ID), "locked" (any field or the whole item is locked), "missing" (the file is missing).

string: unidentified | noPoster | noMetadata | locked | missing

One still frame of an item.

object

• heightinteger

  Height of the original image; omitted when the source did not give it.

• indexintegerRequired

  Position of the still, starting at 0. Deleting one in the middle does not renumber the rest.

• tagstringRequired

  Tag identifying the image content, used to fetch it and to bust caches.

• widthinteger

  Width of the original image; omitted when the source did not give it.

Compact summary of a library item as returned in item lists.

object

• communityRatingnumber

  Community rating of the item, typically on a 0-10 scale.

• dateCreatedstring (date-time)Required

  Time the item was first added to the library (UTC, RFC 3339).

• extraTypeExtraType
• hasPosterbooleanRequired

  True if the item has a poster image.

• idstringRequired

  Unique item ID.

• imageTagstring

  Short hash of the primary poster image; use it as the cache-busting tag when fetching the image.

• indexNumberinteger

  Episode number for an episode, or season number for a season.

• libraryIdstringRequired

  ID of the library that contains the item.

• lockedboolean

  True if any metadata field is locked or the whole item is locked.

• mergedIntostring

  For a series that is a non-primary member of a merged group, the ID of the primary series. Omitted otherwise. Admin lists do not collapse merged series, so this marks them as merged.

• missingboolean

  True if the item's file is missing from disk; the item is cleaned up after the grace period.

• namestringRequired

  Display title of the item.

• originalLanguagestring

  Original language of the work as a BCP 47 tag (for example "ja"). Omitted when unknown.

• originalTitlestring

  Title in the original language.

• parentIndexNumberinteger

  Season number that an episode belongs to.

• productCodestring

  Product code of the item, for example "ABC-123". Omitted when there is none.

• productionYearinteger

  Year of production or first release.

• runtimeTicksinteger (int64)

  Runtime in ticks (1 tick = 100 nanoseconds).

• scrapeStateScrapeState
• seasonIdstring

  For an episode, the ID of its season. Omitted for other types and for episodes directly under a series.

• seriesIdstring

  For an episode or a season, the ID of its series. Omitted for other types.

• sortNamestringRequired

  Name used for sorting.

• typeItemTypeRequired
• versionMemberCountinteger

  For a movie that is the primary entry of a version group, the number of other items merged into it. Omitted when nothing is merged.

• versionOfstring

  For a movie that is a member of a version group, the ID of the primary item. Omitted when the item is not a member. Admin lists do not collapse merged items.

Type of a library item. "Movie" is a film, "Series" a TV show, "Season" a season of a series, "Episode" a single episode, "Folder" a generic folder, "BoxSet" a collection of items, and "Video" a standalone video such as an extra.

string: Movie | Series | Season | Episode | Folder | BoxSet | Video

A background job (scan, scrape, plugin install, poster pre-generation, and so on) with its progress and state.

object

• cancellablebooleanRequired

  True if the job can currently be cancelled with POST /jobs/{id}/cancel: it is in progress and its kind supports cancellation. Scrape queues, finished jobs, paused queues and jobs already being cancelled are not cancellable.

• changedinteger

  Number of items in this batch on which work was actually done (for example thumbnails actually generated); items skipped because they were already complete are not counted. Omitted for jobs without progress reporting. Each image counts toward one outcome, so processed is approximately changed + progressCached + progressNoUpscale + progressNoPoster + progressFailed.

• currentstring

  The item currently being worked on, such as the directory being scanned or the stage of a plugin install.

• errorsinteger

  Number of errors encountered so far.

• etaSecondsinteger

  Estimated remaining time in seconds, roughly (total - processed) / perMinute minutes. Provided only while running and when the rate is above zero.

• finishedAtstring (date-time)

  Time the job finished (UTC, RFC 3339).

• idstringRequired

  Job identifier. For scans it is "scan:{libraryId}"; for plugin installs it is the install job ID.

• kindJobKindRequired
• libraryIdstring

  Library the scan belongs to.

• massMissingPausedboolean

  True if the scan triggered the mass-missing protection and is waiting for confirmation.

• messagestring

  Short summary of the failure reason; when state is "paused" it is the reason for the pause. It is the server's default text; clients should localize using messageCode when present.

• messageCodeJobMessageCode
• messageParamsobject

  Parameters for the message code (numbers, times, names); the contents depend on the code, see JobMessageCode.

• nextRetryAtstring (date-time)

  The earliest time at which a source waiting to be retried is read again. Only for media info read jobs with waiting greater than 0.

• perMinuteinteger

  Number of units completed in the last 60 seconds (the rate, in the same unit as "unit"); when the batch is younger than 60 seconds it is scaled from the elapsed time. Omitted for jobs without progress reporting.

• phasestring: queued | walk | parse | write

  Current phase of a scan. "queued" means a start was requested and the job is waiting for a full-scan slot (the number of concurrent scans is limited); "walk" is directory traversal, "parse" is file parsing, "write" is writing results.

• processedinteger

  Number of units processed so far: directories for scans, bytes for plugin installs, and units of "unit" for pre-generation.

• progressCachedinteger

  Number of units skipped because they were already cached (same unit as "unit"). Present only for jobs that report progress, such as poster pre-generation.

• progressFailedinteger

  Number of images that failed to fetch or resize.

• progressNoPosterinteger

  Number of items skipped because they have no primary poster.

• progressNoUpscaleinteger

  Number of images skipped because the source is not wider than the pre-generated width (the original is served directly on request).

• relatedJobIdstring

  ID of the job that actually performs the work this job handed off to (for example "media_info_read" or "scrape"). Omitted when there is none.

• relatedKindJobKind
• startedAtstring (date-time)

  Time the job started (UTC, RFC 3339).

• stateJobStateRequired
• stopLimitBytesinteger (int64)

  Image cache limit in bytes at the time the batch stopped. Present only when stopReason is set.

• stopReasonstring: cacheBudget

  Reason the batch stopped early (currently only poster pre-generation); omitted otherwise. When set, state is still "succeeded" but the work is incomplete: processed counts only what was done and never reaches total. "cacheBudget" means the image cache reached the pre-generation budget and the remaining images are generated on first request. Kept until the next batch starts.

• stopUsedBytesinteger (int64)

  Image cache bytes in use at the time the batch stopped. Present only when stopReason is set.

• subjectstring

  What the job acts on, not meant to be translated: library name, source host (imports may include the current library name and progress), or plugin ID and version. Omitted when there is no subject.

• systemboolean

  True for an idle system run: trigger is "auto" and changed is 0, meaning everything was already complete and nothing was done. Clients may hide such jobs.

• titlestringRequired

  Default title in Traditional Chinese kept for legacy clients; new clients should localize based on kind and add subject.

• totalinteger

  Total number of units; omitted when unknown. For pre-generation the total is computed when the batch starts (the sum over all queued libraries).

• triggerstring: manual | scan | auto

  What started this batch. "manual" is a manual request, "scan" is the completion of a library scan, and "auto" is the system schedule (after startup and every 6 hours as a backfill). Omitted when the source is unknown.

• unitstring

  Unit of processed and total. Currently only pre-generation reports it, as "images" (number of images). Omitted otherwise.

• waitinginteger

  Number of sources waiting to be retried after a failed media info read (backing off, not counted as pending). Only for media info read jobs; see nextRetryAt.

Kind of background job: library scan, plugin install, metadata scrape, poster pre-generation, upload cleanup, Emby import, NFO sync, media info read, person recheck, collection name fill, person details fill, attention-card action, local re-probe, or rating age refresh.

string: scan | pluginInstall | scrape | posterPregenerate | uploadCleanup | embyImport | nfoSync | mediaInfoRead | personRecheck | collectionNameFill | personDetailsFill | personSourceRefetch | attentionAction | localReprobe | ratingAgeRefresh | backup | scheduledTask

Machine-readable code for a job status message; clients localize it using the job's messageParams. Values: scrapeBatchDone, scrapeRunning, scrapeWaiting, paused, noProvider, rateLimited, collectionsFilled, importingItem, nfoWriteFailed, failedSeeLog, peopleDetailsRunning, peopleDetailsFilled, yieldingToScrape, attentionActionRunning, attentionActionDone and attentionActionQueued. Parameters: scrapeBatchDone has processed, applied, failed, needsIdentify; scrapeRunning has processed, pending, approximate, count, name, providers; scrapeWaiting has processed, pending, approximate; paused has an optional code ("no_provider" or "provider_unavailable") and reason; noProvider means no provider plugin is available; rateLimited has retryAt (RFC 3339) and, for remote media info reads limited with 403 or 429, status (state is "paused"); collectionsFilled has filled, skipped; importingItem has name; nfoWriteFailed has failures; failedSeeLog means the job failed and details are in the server log; peopleDetailsRunning has processed, filled, skipped, remaining; peopleDetailsFilled has filled, skipped; yieldingToScrape means person detail filling is yielding to the scrape queue (state is "paused" and resumes automatically); attentionActionRunning has action, processed, total; attentionActionDone has action, done, skipped, failed; attentionActionQueued has action, count, skipped, failed and means the work was only handed to a queue, with progress shown on the job named by relatedJobId.

string: scrapeBatchDone | scrapeRunning | scrapeWaiting | paused | noProvider | rateLimited | collectionsFilled | importingItem | nfoWriteFailed | failedSeeLog | peopleDetailsRunning | peopleDetailsFilled | yieldingToScrape | attentionActionRunning | attentionActionDone | attentionActionQueued | waitingRetry | readFailures | backupDone | backupInProgress | personRecheckRunning | personSourceRefetchRunning | personSourceRefetchDone

State of a job. "running" is in progress; "paused" means the queue is paused (currently only the scrape queue: paused by an admin, outside the scrape window, or no scrape source available), nothing is being processed, and the reason is in message; a paused job is not running and cannot be cancelled; "cancelling" is being cancelled; "succeeded", "failed" and "cancelled" are final states.

string: running | paused | cancelling | succeeded | failed | cancelled

A media library with its root paths, item count, scan status and related flags.

object

• collectionTypeLibraryKindRequired
• coversLibraryCovers
• hasStrmSourcesboolean

  True if the library contains .strm (pointer file) sources. Admin UIs use it to show that the strm plugin is needed. The result is cached for about 15 seconds, only non-missing versions are considered, and the field is omitted when it cannot be determined.

• idstringRequired

  Unique library ID.

• itemCountinteger

  Number of works in the library: movies and series each count once; seasons, episodes, extras and missing items are excluded. Omitted when the count is temporarily unavailable (never reported as 0).

• lastScannedAtstring (date-time)

  Time the most recent scan completed successfully (UTC), from the scanner's in-memory state. Omitted after a server restart before any scan completes, while a scan is running, when the last scan failed or was cancelled, or when no scanner is attached.

• namestringRequired

  Display name of the library.

• nfoSyncSuggestedboolean

  True only in the response to an update that turned "writeBack" (write NFO files) from off to on, to suggest syncing the whole library to NFO with POST /libraries/{id}/nfo-sync. Not present in other responses.

• optionsLibraryOptionsRequired
• pathsarray of stringRequired

  List of absolute root directory paths of the library.

• remoteReadsSuggestedboolean

  True only in the response to an update that changed the hosts remote sources may connect to (remoteAllowedHosts). Reads that failed permanently (address policy refusal, 404) are given up and not retried automatically, so suggest reading again with POST /libraries/{id}/media-info-reads (given-up reads are re-enabled). Saving settings never starts that work itself. Not present in other responses.

• rescanRewriteboolean

  True only together with rescanSuggested when the externalAudio switch changed. Start the scan with rewrite set to true; otherwise a full scan does not rewrite directories whose files are unchanged.

• rescanSuggestedboolean

  True only in the response to an update that changed the exclusion rules (excludeKeywords, excludeExtensions, excludeSmallerThanBytes) or the externalAudio switch. A quick scan does not revisit directories whose modification time is unchanged, so already-indexed files would not follow the new rules; suggest a full scan with POST /libraries/{id}/scan. Saving settings never starts the scan itself. Files that become missing because of the new rules are subject to the usual mass-missing protection. Not present in other responses.

• scrapePendinginteger

  Number of items in the library waiting to be scraped (same measure as the scrapePending count of the admin attention summary, for this library). Only present in GET /libraries and GET /libraries/{id}; cached for about 5 seconds and omitted when it cannot be counted.

• scrapeRequeueCountinteger

  Used with scrapeRequeueSuggested - how many items would be queued; omitted when the scraper cannot count.

• scrapeRequeueSuggestedboolean

  True only in the response to an update that changed the library from not scraping (no providers selected or auto scrape off) to scraping. Items already indexed stay "not queued for scraping" until an admin queues them with POST /admin/scrape/requeue; saving settings never queues them itself. Not present in other responses.

• strmPluginEnabledboolean

  True if the strm plugin is enabled. When it is not, background reads (mediaInfoTiming), embedded subtitles and video capture have no effect on .strm items. The server itself still supports .strm indexing, scraping, playback and media info reads during playback.

Source of the effective library cover. "custom" is a cover uploaded by an admin, "scanned" is an image found in the library (such as folder.jpg), and "auto" is the automatic collage stored by the server. An automatic cover is generated once and kept; use POST /libraries/{id}/cover/{kind}/regenerate to replace it.

string: custom | scanned | auto

Library cover images. The effective cover is, in order, the admin-uploaded custom cover, an image from the library, or an automatic collage. Images are fetched with GET /images/{libraryId}/{primary|thumb}?tag=. A version with no source is omitted.

object

• customPrimarybooleanRequired

  True if the portrait cover is currently an admin-uploaded custom cover (it can be reverted to automatic).

• customThumbbooleanRequired

  True if the landscape cover is currently an admin-uploaded custom cover.

• primarystring

  Tag of the effective portrait (2:3) cover.

• primaryFinalboolean

  True if the automatic portrait cover is final (it collects 4 different posters); false means a temporary cover that may still change as the library grows. Present only when primarySource is "auto".

• primaryGeneratedAtstring (date-time)

  Time the automatic portrait cover was generated or last regenerated (UTC). Present only when primarySource is "auto".

• primarySourceLibraryCoverSource
• thumbstring

  Tag of the effective landscape (16:9) cover.

• thumbFinalboolean

  True if the automatic landscape cover is final. Present only when thumbSource is "auto".

• thumbGeneratedAtstring (date-time)

  Time the automatic landscape cover was generated (UTC). Present only when thumbSource is "auto".

• thumbSourceLibraryCoverSource

Content type of a library: "movies", "tvshows", or "mixed" (both).

string: movies | tvshows | mixed

Library-level settings: allowed hosts for remote sources, metadata and scraping options, scan exclusions and subtitle options. Per-library settings owned by plugins (such as delivery) are available at GET /libraries/{id}/plugins/{pluginId}/settings.

object

• allowDeletionbooleanRequired

  Allows deleting this library's items and their files on disk. Off by default, which keeps the library read-only. When enabled, the server test-writes and deletes a temporary file in every root directory and returns 400 naming the directory if it is not writable.

• autoScrapebooleanRequired

  Automatically scrape newly added items that have no NFO (default on). When off, new items are not queued; items already queued are unaffected.

• autoSubtitleLanguagesarray of string

  Languages (BCP 47, in order) for which subtitles are downloaded automatically when missing. See LibraryOptionsUpdate.autoSubtitleLanguages.

• backgroundPluginsarray of string

  IDs of the background plugins enabled for this library. They must be installed plugins, and a plugin must itself be enabled to run.

• badgesOnPostersboolean

  Draw poster badges (per the server settings badge rules) into the main poster served to third-party players (Emby and Jellyfin compatible interface). Off by default. The web and apps always overlay badges.

• disableSeriesMergeboolean

  Disables merged display of series that share the same TMDB ID. Series and mixed libraries merge by default (false); movie libraries ignore this setting. Toggling changes only display, not any item ID, and merge groups are recomputed in the background (eventually consistent).

• effectiveEmbeddedSubtitlesbooleanRequired

  Effective value of embeddedSubtitles after applying the storage-based default.

• effectiveIntroDetectionbooleanRequired

  Effective value of introDetection after applying the storage-based default.

• effectiveMediaInfoTimingMediaInfoTimingRequired
• effectiveReadConcurrencyintegerRequired

  Effective number of concurrent reads: the explicitly set value, otherwise 2 for cloud storage or the global probe limit for local storage.

• effectiveSubtitleFullReadLimitBytesinteger (int64)Required

  Effective whole-file read limit in bytes: the explicitly set value, otherwise 8 GiB for local storage and 0 for cloud storage. 0 means files are never read whole.

• effectiveVideoCapturebooleanRequired

  Effective value of videoCapture after applying the storage-based default.

• embeddedSubtitlesboolean

  Whether embedded subtitles are extracted from videos during playback. null follows the storage type (on for local, off for cloud). On cloud storage embedded subtitles require reading the whole file.

• excludeExtensionsarray of stringRequired

  File extensions skipped during scans, lowercase with a leading dot (for example ".nfo"). Empty by default.

• excludeKeywordsarray of stringRequired

  Files skipped during scans: keywords are matched as whole words (word boundaries, case-insensitive) against the file name stem (without extension), never against directory names. Empty by default. Trailers are still classified as extras and the built-in sample rule still applies. Files that become missing because of new rules are subject to the usual mass-missing protection.

• excludeSmallerThanBytesinteger (int64)Required

  Media files smaller than this size in bytes are skipped during scans; 0 disables the filter (default). A file exactly at the threshold is not excluded. Does not apply to .strm files.

• externalAudioboolean

  Scan and serve external audio track files (default true). See LibraryOptionsUpdate.externalAudio.

• fillMissingFromProviderbooleanRequired

  Also queue new items that have an NFO for scraping, so providers fill empty fields and missing images without overwriting NFO values. Off by default.

• imageSourcesarray of string

  Selected image source plugin IDs, in order. See LibraryOptionsUpdate.imageSources.

• importCollectionsbooleanRequired

  Create collections from NFO files and providers. On by default.

• introDetectionboolean

  Detect intros and credits from audio fingerprints, which reads the audio of every episode. null follows the storage type (on for local storage, off for network storage). When off, applying a segment to the season copies the same times, and community segments are checked with a short audio sample.

• massMissingThresholdnumber (double)Required

  Threshold of the mass-missing protection, from 0 to 1 (default 0.2). If a scan would mark more than this fraction of items missing, marking pauses until an admin confirms. 1 disables the protection.

• mediaInfoTimingMediaInfoTiming

  When media info is read; null follows the storage type (during scan for local, in the background for cloud).

• metadataLanguagestringRequired

  Scrape language as a BCP 47 tag, which must be a language supported by the server (currently en, zh-CN, zh-TW) and is stored in canonical form. An empty string follows the server default language. If a translation is unavailable the language fallback order is used, then the original text.

• metadataProvidersarray of stringRequired

  IDs of the selected metadata provider plugins. An empty array means no provider is used (no scraping and no manual identify). See LibraryOptionsUpdate.metadataProviders.

• missingGraceHoursintegerRequired

  Grace period in hours before missing items are purged by the scheduler. Defaults to 168 (7 days) when unset.

• readConcurrencyinteger

  Number of file reads this library performs at the same time to read media info (scan probing, re-reading media info, background reads, video capture), still bounded by the global limit. null follows the storage type; effectiveReadConcurrency holds the effective value.

• realtimeMonitorbooleanRequired

  Watch the file system for changes (default on). When on, the scanner watches root directories so additions, renames and deletions show up quickly. Network mounts (NFS, SMB) and some FUSE file systems cannot be watched and rely on scheduled and manual scans; the actual state is in the watch field of GET /scans/status.

• recognizersarray of string

  IDs of the selected name recognizer plugins, in order. An empty array means no recognizer is used. See LibraryOptionsUpdate.recognizers.

• remoteAllowedHostsarray of stringRequired

  Hosts that remote sources may connect to, optionally with a port (for example "media.example:5678"). Matching is case-insensitive and values are stored in lowercase. Values must not contain a scheme, path, query string, "@" or whitespace. An empty array allows any host, but the server refuses at connect time targets resolving to loopback, link-local (including 169.254.169.254) or unspecified addresses. A non-empty array allows only the listed hosts, which are exempt from those address restrictions. Every redirect hop is checked again, so CDN hosts that a cloud drive redirects to must also be listed.

• scansSuspendedboolean

  Suspends automatic scans for this library. When true, no initial scan runs after creation and scheduled scans and real-time monitoring are off; manually triggered scans still work. Used by import flows to avoid scanner interruptions.

• segmentProvidersarray of string

  IDs of the selected segment provider plugins, in order. An empty array means community segments are not queried. See LibraryOptionsUpdate.segmentProviders.

• storageLibraryStorageRequired
• subtitleFullReadLimitBytesinteger (int64)

  Maximum file size in bytes for which the whole file may be read when embedded subtitles cannot be extracted otherwise (no index allows reading only the subtitle blocks, for example non-mkvmerge muxes or MKV files lacking statistics tags). Larger files are not extracted. 0 never reads whole files; null follows the storage type (8 GiB for local, 0 for cloud). effectiveSubtitleFullReadLimitBytes holds the effective value.

• unratedAgeinteger: 0 | 7 | 12 | 16 | 18

  Age assumed for content in this library that has no rating or an unrecognized one: 0 means all ages (such as home videos) and is the default; set 18 to block unrated content. Affects only members with parental controls. Responses always carry the effective value; omit it on update to keep the current one. Changing it requires the parental-controls license, otherwise 403 "license_required"; an unchanged value is not checked.

• useNfobooleanRequired

  Use local NFO files as a metadata source (default on). When off the scanner does not read NFO metadata; values already read are kept and can be overwritten by providers.

• videoCaptureboolean

  Capture a frame from the video (or use an embedded cover) as the image for items that have none. null follows the storage type (on for local, off for cloud).

• writeBackbooleanRequired

  Write scrape results to NFO files and images, only filling in what is missing and never overwriting existing files. Off by default.

Request body for updating library options. remoteAllowedHosts is required (it replaces the whole list); other fields keep their current value when omitted. A value of 0 for missingGraceHours or massMissingThreshold is treated as omitted.

object

• allowDeletionboolean

  Allow deleting this library's items and files on disk; see LibraryOptions.allowDeletion.

• autoScrapeboolean

  Automatically scrape new items without an NFO; see LibraryOptions.autoScrape.

• autoSubtitleLanguagesarray of string

  Languages (BCP 47, in order) for which the background queue automatically downloads subtitles when missing. An empty array (default) disables it. Only videos with no subtitle in that language at all are filled; the work is low priority, limited by the upstream quota, and manual downloads take precedence. Values are normalized by trimming whitespace and removing empty and duplicate entries (case-insensitive). Omit to keep the current value.

• backgroundPluginsarray of string

  IDs of installed background plugins to enable for the library; omit to keep the current value. See LibraryOptions.backgroundPlugins.

• badgesOnPostersboolean

  Draw badges into the main poster served to third-party players; see LibraryOptions.badgesOnPosters. Omit to keep the current value.

• disableSeriesMergeboolean

  Disable merged display of series with the same TMDB ID; see LibraryOptions.disableSeriesMerge.

• embeddedSubtitlesboolean

  Extract embedded subtitles during playback; see LibraryOptions.embeddedSubtitles.

• excludeExtensionsarray of string

  File extensions to skip during scans; see LibraryOptions.excludeExtensions. Same rules as excludeKeywords, and a leading dot is added if missing; apart from the leading dot, an extension must not contain dots or whitespace. Invalid values return 400 "field_invalid" with field "excludeExtensions".

• excludeKeywordsarray of string

  Keywords to skip during scans; see LibraryOptions.excludeKeywords. Omit to keep the current value; an empty array excludes nothing. Values are normalized (trimmed, lowercased, empty and duplicate entries removed) and then validated: at most 50 entries, each at most 64 characters (16 for extensions) and without "/" or backslash, otherwise 400 "field_invalid" with field "excludeKeywords". If the storage does not support exclusion rules yet, writing a non-empty list returns 503 "not_enabled".

• excludeSmallerThanBytesinteger (int64)

  Skip media files smaller than this many bytes; see LibraryOptions.excludeSmallerThanBytes. Omit to keep the current value; 0 disables. Values outside 0 to 1 TiB (1099511627776) return 400 "field_invalid" with field "excludeSmallerThanBytes". Changing it returns rescanSuggested like changing keywords (no scan is started).

• externalAudioboolean

  Scan and serve external audio track files (default true). When off the scanner does not collect external audio files and already collected ones are not served. Omit to keep the current value.

• fillMissingFromProviderboolean

  Also scrape items that have an NFO to fill missing fields; see LibraryOptions.fillMissingFromProvider.

• followStoragearray of LibraryPresetField

  Settings to reset to the recommended value for the library's storage type (stored as null). Giving a value for a setting and listing it here at the same time returns 400 "field_invalid" with field set to that setting's name.

• imageSourcesarray of string

  Image source plugin IDs whose image candidates are merged in order when scraping. Each must be an installed plugin that declares images.* (see GET /image-providers), otherwise 400 "image_source_not_installed" (params.field, params.provider). An empty array (default) uses only the images that metadata providers supply. Omit to keep the current value.

• importCollectionsboolean

  Create collections from NFO and providers; see LibraryOptions.importCollections.

• introDetectionboolean

  Detect intros and credits from audio fingerprints; see LibraryOptions.introDetection. Omit to keep the current value; use followStorage to go back to the storage default.

• massMissingThresholdnumber (double)

  Mass-missing protection threshold from 0 to 1; see LibraryOptions.massMissingThreshold. 0 is treated as omitted.

• mediaInfoTimingMediaInfoTiming
• metadataLanguagestring

  Scrape language (BCP 47); see LibraryOptions.metadataLanguage.

• metadataProvidersarray of string

  Provider plugin IDs selected for the library and tried in order; each must be an installed provider. An empty array means no provider is used: no scraping, manual identify returns 409 "library_no_providers", and new items are not queued. When creating a library, omitting this (or omitting options) selects all available movie or series providers; an empty array is stored as given. Providers installed later are not added to existing libraries. Providers in the list that are not installed or are disabled are treated as unselected.

• missingGraceHoursinteger

  Grace period in hours before missing items are purged; see LibraryOptions.missingGraceHours. 0 is treated as omitted.

• readConcurrencyinteger

  Number of concurrent media info reads, 1 to 8. Omit to keep the current value; values out of range return 400 "field_invalid" with field "readConcurrency". To go back to following the storage type use followStorage.

• realtimeMonitorboolean

  Watch the file system for changes; see LibraryOptions.realtimeMonitor.

• recognizersarray of string

  Name recognizer plugin IDs called in order; each must be an installed plugin that declares media.recognize (see GET /recognizers). When scraping, the first recognizer that returns a result wins. An empty array uses no recognizer, and scraping sends only the name and year inferred by the scanner. When creating a library, omitting this (or omitting options) selects all available recognizers; an empty array is stored as given. Recognizers installed later are not added to existing libraries.

• remoteAllowedHostsarray of stringRequired

  Hosts remote sources may connect to; see LibraryOptions.remoteAllowedHosts. Required; it replaces the whole list.

• scansSuspendedboolean

  Suspend automatic scans for the library; see LibraryOptions.scansSuspended. Omit to keep the current value.

• segmentProvidersarray of string

  Segment provider plugin IDs queried in order. Each must be an installed plugin that declares segments.provider (see GET /segment-providers), otherwise 400 "segment_provider_not_installed" (params.field, params.provider). An empty array (the default, also for new libraries) means community segments are not queried. Omit to keep the current value.

• storageLibraryStorage

  Storage type of the library; see LibraryOptions.storage. Omit to keep the current value; invalid values return 400 "field_invalid" with field "storage". When creating a library without it and .strm files are found under the roots (directories are listed, contents are not read), it defaults to "cloud".

• subtitleFullReadLimitBytesinteger (int64)

  Maximum file size in bytes for whole-file reads when extracting embedded subtitles; see LibraryOptions.subtitleFullReadLimitBytes. Range 0 to 1 TiB (1099511627776); omit to keep the current value; out of range returns 400 "field_invalid" with field "subtitleFullReadLimitBytes". To go back to following the storage type use followStorage.

• unratedAgeinteger: 0 | 7 | 12 | 16 | 18

  Age assumed for unrated or unrecognized content in this library: 0 means all ages (such as home videos), the default; set 18 to block unrated content. Affects only members with parental controls. Omit to keep the current value. Changing it requires the parental-controls license, otherwise 403 "license_required"; an unchanged value is not checked.

• useNfoboolean

  Use local NFO files as a metadata source; see LibraryOptions.useNfo.

• videoCaptureboolean

  Capture video frames for items without images; see LibraryOptions.videoCapture.

• writeBackboolean

  Write scrape results to NFO files and images; see LibraryOptions.writeBack.

A setting that can follow the recommended value for the library's storage type: readConcurrency, mediaInfoTiming, embeddedSubtitles, videoCapture, subtitleFullReadLimitBytes or introDetection. Used by LibraryOptionsUpdate.followStorage.

string: readConcurrency | mediaInfoTiming | embeddedSubtitles | videoCapture | subtitleFullReadLimitBytes | introDetection

Kind of storage the library's files are on, chosen by the user and not auto-detected. "local" is a local or LAN disk; "cloud" is a cloud drive mount (slow or metered reads). .strm libraries can store either value and the server ignores it for them. Creating a "cloud" library without an explicit realtimeMonitor turns real-time monitoring off by default, since cloud mounts do not deliver file change notifications.

string: local | cloud

When media info is read. "scan" reads it during the scan (recommended for local storage); "background" only creates items during the scan and reads media info slowly in the background according to the read concurrency, yielding when someone is playing (recommended for cloud storage); "playback" reads it only at playback time.

string: scan | background | playback

A playable media file (version) of an item, with its container, size, bitrate and streams.

object

• bitrateinteger (int64)Required

  Overall bitrate in bits per second.

• containerstringRequired

  Container file extension (mkv, mp4, and so on).

• idstringRequired

  Unique media source ID.

• itemIdstringRequired

  ID of the item this media source belongs to.

• missingboolean

  True if the file is missing on disk.

• namestringRequired

  Version name (for example "4K" or "Director's Cut"); empty by default.

• pathstringRequired

  File path or remote URL of the media source.

• probeFailureProbeFailure

  Reason probing a local file failed. The file is still indexed but has no media info (streams contain only plugin-provided tracks and the duration is 0). It disappears once a later probe (scan or playback re-probe) succeeds. Omitted for remote sources and for successfully probed files.

• sizeinteger (int64)Required

  File size in bytes.

• streamsarray of MediaStreamRequired

  Video, audio and subtitle streams of the media source.

A single video, audio or subtitle stream in a media source.

object

• bitrateinteger (int64)

  Stream bitrate in bits per second.

• channelLayoutstring

  Audio channel layout, for example "5.1".

• channelsinteger

  Number of audio channels.

• codecstringRequired

  Codec name (h264, hevc, aac, subrip, ass, webvtt, and so on).

• externalPathstring

  File path of an external subtitle file.

• heightinteger

  Video height in pixels.

• indexintegerRequired

  Stream index: the ffprobe index for embedded streams, or the sequence number for external subtitles.

• isDefaultboolean

  True if the stream is flagged as the default track.

• isExternalboolean

  True if the stream is an external subtitle file.

• isForcedboolean

  True if the stream is flagged as forced.

• languagestring

  ISO 639-2/B language code (chi, eng, jpn, and so on).

• resolutionNamestring

  Display name of a video stream's resolution (SD, 720p, 1080p, 1440p, 4K, 8K). A stream qualifies if either its width or height reaches the tier. Omitted when width and height are unknown.

• sampleRateinteger

  Audio sample rate in Hz.

• titlestring

  Track title.

• typeStreamTypeRequired
• widthinteger

  Video width in pixels.

How far a member can use the server under the plan's member limit: "full" (kept, or within the limit), "admin-only" (an administrator that is not kept; can only open the admin site) or "denied" (a member that is not kept; cannot sign in to the viewer). Disabled members do not count and are always "full".

string: full | admin-only | denied

Scrape status and locks of an item.

object

• dateSavedstring (date-time)

  Time the metadata last actually changed (UTC, RFC 3339).

• lockDatabooleanRequired

  True if the whole item is locked so that only manual edits can change it.

• lockedFieldsarray of stringRequired

  Locked metadata fields, using the same names as Emby's MetadataFields (for example Name, Overview, Genres, Cast).

• providerstring

  ID of the plugin that provided the match. Omitted when there is no match.

• providerItemIdstring

  ID of the item at the provider. Omitted for seasons and episodes that have no separate ID.

• scrapeErrorstring

  Reason a scrape failed or the item needs identification.

• scrapeStateScrapeStateRequired
• scrapedAtstring (date-time)

  Time metadata was last fetched from a provider (UTC, RFC 3339).

An ID with its display name.

object

• idstringRequired

  ID of the referenced object.

• namestringRequired

  Display name of the referenced object.

Parental controls for one member (a paid add-on). Rules are always enforced server-side and blocked content is completely hidden; administrators are not restricted. Values are normalized (tags and genres lowercased, de-duplicated and sorted) and validated before storing; invalid input returns 400.

object

• allowedItemsarray of string

  Item IDs explicitly allowed regardless of age, tags and genres. Setting it on a series applies to the whole series.

• blockedGenresarray of string

  Genres that are blocked.

• blockedItemsarray of string

  Item IDs explicitly blocked; this has the highest priority.

• blockedTagsarray of string

  Tags that are blocked.

• dailyLimitMinutesinteger

  Daily viewing limit in minutes, counted per date in the server time zone and accumulated across devices. 0 means no limit.

• maxAgeinteger: 0 | 7 | 12 | 16 | 18Required

  Highest age tier the member may watch (0, 7, 12, 16 or 18); 0 allows only all-ages content. Ratings are converted to an actual age for comparison (PG-13 counts as 13, so a 12 limit blocks it). Content with no rating uses the library's unratedAge.

• windowsarray of ParentalWindow

  Time windows during which viewing is allowed; empty means no time restriction.

One allowed viewing window, interpreted in the server time zone. If endMinute is less than or equal to startMinute the window crosses midnight; for example Friday 20:00 to Saturday 01:00 is days=[5], startMinute=1200, endMinute=60.

object

• daysarray of integerRequired

  Days of the week the window applies to, 0 for Sunday through 6 for Saturday (the day on which the window starts).

• endMinuteintegerRequired

  End of the window as minutes after midnight (0 to 1439).

• startMinuteintegerRequired

  Start of the window as minutes after midnight (0 to 1439).

A person credited on a title, with the role they play and their position in the credits.

object

• idstringRequired

  Person ID.

• imageTagstring

  Tag identifying the current person image, usable for cache busting.

• kindPersonKindRequired
• namestringRequired

  Display name of the cast or crew member.

• orderinteger

  Position of this person in the title's credits, ascending.

• rolestringRequired

  Character played or job held on the title.

• sharedCountinteger

  Only present in the collaborators list of a person's detail: the number of titles this person has in common with the person being viewed.

Kind of credit a person has on a title: "Actor", "Director", "Writer", "Producer", "GuestStar" (guest appearance in an episode) or "Composer".

string: Actor | Director | Writer | Producer | GuestStar | Composer

How the media is delivered to the player. "direct_play" sends the file as is, "direct_stream" changes only the container, "audio_transcode" converts the audio while copying the video, "proxy" means the server fetches remote content on the player's behalf, and "redirect" sends the player straight to the remote source. Remote sources use "proxy" or "redirect"; other sources use one of the first three.

string: direct_play | direct_stream | audio_transcode | proxy | redirect

One page of playback history records.

object

• itemsarray of PlayRecordRequired

  Playback records on this page.

• nextCursorstring

  Present only when another page exists; pass it back as cursor with the same filters to fetch the next page.

Network the player is on, determined from the request's source address: "lan" for the local network, "wan" for the external network. The rules match the Emby-compatible layer (addresses forwarded by trusted proxies, extra LAN subnets, WAN-only ports). PlaybackInfo.network is omitted when the source address cannot be classified.

string: lan | wan

Where the played content lives: "local" for a file on the server's storage, "remote" for a remote source.

string: local | remote

One playback history record for a member watching an item on a device.

object

• atstring (date-time)Required

  Time playback started, in UTC.

• deliveryPlayDeliveryRequired
• devicestringRequired

  Name of the device that played the item.

• deviceIdstringRequired

  Identifier of the device.

• durationSecnumber (double)Required

  Total duration of the item in seconds.

• endedAtstring (date-time)Required

  Time playback ended, in UTC.

• episodestring

  Episode label for episodes, for example S01E04.

• finishedbooleanRequired

  True when the member watched 90% or more of the item.

• idstringRequired

  Record ID.

• ipstring

  Source address of the player. Omitted once the record is older than the retention period (90 days by default).

• itemDeletedboolean

  True when the item no longer exists.

• itemIdstringRequired

  ID of the played item.

• kindstring: movie | episode | videoRequired

  Type of the played item: "movie", "episode" or "video".

• memberstringRequired

  Name of the member who played the item.

• memberIdstringRequired

  ID of the member who played the item.

• networkPlayNetworkRequired
• originPlayOriginRequired
• percentnumber (double)Required

  Furthest position reached as a percentage of the item's duration; 0 when the duration is unknown.

• playerstringRequired

  Name of the player application.

• sessionsintegerRequired

  Number of playback sessions merged into this record.

• titlestring

  Title of the played item.

• watchedSecnumber (double)Required

  Time actually played in seconds, excluding pauses.

A currently active playback session.

object

• bandwidthKbpsintegerRequired

  Actual traffic passing through the server in kbit/s. Always 0 for redirects and direct file reads, because the traffic does not go through the server.

• bitrateKbpsinteger

  Bitrate of the media itself in kbit/s, taken from media info. Omitted when unknown.

• deliveryPlayDeliveryRequired
• devicestringRequired

  Name of the device playing the item.

• durationSecnumber (double)Required

  Total duration of the item in seconds.

• episodestring

  Episode label, for example S01E04.

• idstringRequired

  Session ID.

• itemDeletedboolean

  True when the item has been deleted or cannot be read; in that case title is absent.

• itemIdstringRequired

  ID of the item being played.

• memberstringRequired

  Name of the member playing (user-supplied data, not server text).

• memberIdstringRequired

  ID of the member playing.

• networkPlayNetworkRequired
• originPlayOriginRequired
• pausedbooleanRequired

  True when playback is currently paused.

• playerstringRequired

  Name of the player application.

• positionSecnumber (double)Required

  Current playback position in seconds.

• progressnumber (double)Required

  Playback progress as a fraction of the duration, from 0 to 1.

• seasonIdstring

  ID of the season an episode belongs to, for showing the season poster. Omitted when the item is not an episode or has no season.

• seriesIdstring

  ID of the series an episode belongs to, for showing the series poster. Omitted when the item is not an episode.

• startedAtstring (date-time)Required

  Time the session started, in UTC.

• stoppablebooleanRequired

  Whether the server is able to ask this player to stop.

• titlestring

  Title of the item; for an episode, the name of its series.

Attribution required by a data source, such as the text and logo a provider's terms demand. Clients that display this data must show it.

object

• linkstring

  URL the attribution links to.

• logoUrlstring

  URL of the logo to display.

• textstring

  Attribution text to display.

A paid feature a plugin uses, derived by the server from the capabilities the plugin declares. The hint shown to the user ("this feature needs a plan to take effect") is the server UI's own text.

object

• entitledbooleanRequired

  Whether the current license covers the feature. When false the plugin can still be enabled, but the capabilities behind the feature are not used.

• featurestringRequired

  Feature code.

One runtime figure reported for a plugin.

object

• atstring (date-time)

  Time related to the figure (for example the last success); omitted when there is none.

• codestringRequired

  Stable code naming the figure; clients translate it.

• unitPluginStatUnitRequired
• valueinteger (int64)Required

  The figure itself, in the given unit (0 when the unit is "time").

Unit of PluginStat.value: "count" for counts, "bytes" for sizes, "time" when only "at" is meaningful.

string: count | bytes | time

A schedulable task registered by a plugin, shown on the plugin settings page with a run-now button (POST /admin/schedules/{task}/run).

object

• lastFinishedAtstring (date-time)

  Time the last run finished, in RFC 3339 format.

• lastResultScheduleResult
• namesobjectRequired

  Display names keyed by language code (en is always present).

• nextRunAtstring (date-time)

  Next scheduled run time in RFC 3339 format; omitted when paused or when the trigger has no scheduled time.

• pausedbooleanRequired

  True if the schedule is paused.

• ruleScheduleRuleRequired
• runningbooleanRequired

  True if a run of this task is currently in progress.

• taskScheduleTaskRequired

Category of a failed probe of a local file; the raw error goes only to the logs. "invalid" means the file is corrupt or empty, "timeout" means the probe timed out, "permission_denied" means the file cannot be read, "unreachable" means it cannot be reached (for example a network mount that is temporarily down), and "unknown" covers anything else. Missing files and disconnected mounts are not recorded by the scanner, so those cases have no category.

string: permission_denied | unreachable | timeout | invalid | link_gone | not_media | unknown

Category of the most recent error of a plugin or metadata provider; the raw error goes only to the logs. "crashed" means the provider crashed, "needs_configuration" means its settings are missing or invalid, "auth_failed" means authentication failed (invalid key), "rate_limited" means the upstream throttled requests, "unreachable" means the upstream cannot be reached, "timeout" means a request timed out, and "unknown" covers anything else.

string: crashed | needs_configuration | auth_failed | rate_limited | unreachable | timeout | unknown

Options for refreshing metadata of an item or library.

object

• modestring: missing | replaceAllRequired

  "missing" fills in only metadata that is absent; "replaceAll" replaces existing metadata.

• recursiveboolean

  Applies to items only: also processes the children of a series, season or folder. Defaults to false. For a library the whole library is always processed.

• replaceImagesboolean

  Also replaces images that came from providers. Defaults to false.

Information about a software release.

object

• notesUrlstring

  HTTPS URL of the release notes. Omitted when there are none.

• publishedAtstring (date-time)

  Time the release was published, in UTC.

• versionstringRequired

  Version string of the release.

A remote trailer: an http(s) URL that can be opened directly (for example a YouTube link). Trailers are listed in order of preference, and the first is the preferred one.

object

• kindstring

  Kind of video, such as trailer, teaser, clip, featurette or behind_the_scenes. Unrecognized values are stored as given.

• languagestring

  Language as a BCP 47 tag. Omitted when unknown.

• namestring

  Display name of the trailer.

• officialboolean

  True when the video was uploaded by the studio.

• urlstringRequired

  Trailer URL; only http and https are accepted.

Result of a request to re-scrape metadata for a set of items.

object

• queuedintegerRequired

  Number of items queued for scraping.

• skippedintegerRequired

  Number of items skipped because they already have a match and the data layer cannot mark them stale. Normally 0.

Reason a library root is offline; the raw error goes only to the logs. Values are "not_found", "permission_denied", "not_directory", "not_mounted", and "unknown" when the cause cannot be classified.

string: not_found | permission_denied | not_directory | not_mounted | unknown

Reachability status of a library root directory.

object

• checkedAtstring (date-time)

  Time of the last reachability check, in UTC.

• lastOnlinestring (date-time)

  Time the root was last reachable, in UTC. Omitted if it has never been reachable.

• messagestring

  Raw server text describing why the root is offline, intended for logs and older clients. Clients should translate reasonCode instead of displaying it.

• onlinebooleanRequired

  True when the root is currently reachable.

• pathstringRequired

  Filesystem path of the root.

• reasonCodeRootErrorCode

An error recorded during a library scan.

object

• errorstringRequired

  Error message.

• idstringRequired

  Error record ID.

• libraryIdstringRequired

  ID of the library being scanned.

• occurredAtstring (date-time)Required

  Time the error occurred, in UTC.

• pathstringRequired

  Path of the file or directory that caused the error.

Scan mode: "quick" compares directory modification times, "full" checks every file individually.

string: quick | full

Request body for starting a library scan.

object

• modeScanMode
• rewriteboolean

  Ask the scanner to rewrite directories before scanning (used after the externalAudio switch changed, see Library.rescanRewrite). Ignored when the scanner does not support it.

State of a scan: "idle" nothing has run, "running" a scan is in progress, "cancelling" cancellation was requested and is in progress, "completed" finished successfully, "failed" ended with an error, "cancelled" was cancelled.

string: idle | running | cancelling | completed | failed | cancelled

Live progress and state of the scan for one library.

object

• addedinteger

  Number of items added so far by the current scan.

• changedinteger

  Number of existing items updated so far by the current scan.

• currentDirstring

  Directory the scan is currently walking.

• currentPathstring

  File or directory currently being processed; more specific than currentDir.

• errorsintegerRequired

  Number of errors encountered by the scan.

• finishedAtstring (date-time)

  Time the scan finished, in RFC 3339 format. Omitted while the scan is running.

• libraryIdstringRequired

  Identifier of the library this status belongs to.

• massMissingPausedboolean

  True when the mass-missing safeguard has paused marking items as missing until an administrator confirms (see GET /scans/mass-missing).

• messagestring

  Human-readable status text or the reason for a failure.

• missinginteger

  Number of items marked missing. While the mass-missing safeguard is paused, this is the number that would be marked.

• modeScanModeRequired
• phasestring: queued | walk | parse | write

  Current phase of the scan: "queued" (requested and waiting for a full-scan slot, since the number of concurrent scans is limited), "walk" (traversing directories), "parse" (parsing file names and probing media), "write" (writing results to the database).

• processedintegerRequired

  Number of directories processed so far.

• rootsarray of RootStatus

  Most recent online-status check for each root directory of the library.

• startedAtstring (date-time)

  Time the scan started, in RFC 3339 format.

• stateScanStateRequired
• totalinteger

  Number of directories currently known to need processing, in the same unit as processed. It can grow while walking and is omitted when unknown.

• watchstring: watching | disabled | unsupported | limit | pending

  State of live file-system watching: "watching" (active), "disabled" (turned off in settings), "unsupported" (the file system does not support it, for example network mounts, so only scheduled scans run), "limit" (the system watch limit was reached, falls back to scheduled scans), "pending" (not ready yet, for example a root is temporarily unreachable). Omitted when not reported.

• watchMessagestring

  Raw server text explaining an "unsupported" or "limit" watch state. Kept for legacy clients; use the watch reason code for display.

• watchReasonCodeWatchReasonCode

Schedule configuration and run state for one schedulable task kind.

object

• allowedTriggersarray of ScheduleTriggerRequired

  Trigger types this task kind supports, in suggested display order.

• allowsAfterScanbooleanRequired

  True if this task kind can be configured to also run after a scan.

• defaultRuleScheduleRuleRequired
• descriptionsobject

  Description of a plugin task by language code; omitted for built-in tasks and tasks without one.

• isDefaultbooleanRequired

  True when the schedule has not been changed and follows the built-in default.

• lastErrorCodestring

  Error category of the last failed run, present only when the last result is "failed": for example "not_found", "permission_denied", "unreachable", "timeout", "invalid", "unknown". Scan tasks can also report "library_root_unavailable" (a library root is inaccessible, such as a dropped mount) and "scan_failed" (failed for another reason); these two come with lastErrorLibraries.

• lastErrorLibrariesarray of string

  IDs of the libraries involved in the last failure, in ascending ID order. Omitted when none; present only when the last result is "failed".

• lastFinishedAtstring (date-time)

  Time the last run finished, in RFC 3339 format.

• lastMessagestring

  One-line result the task reported on its last run (plugin tasks only). Omitted when there is none.

• lastResultScheduleResult
• lastStartedAtstring (date-time)

  Time the last run started, in RFC 3339 format.

• namesobject

  Display names of a plugin task keyed by language code (en is always present). Omitted for core tasks, which clients translate from the task ID.

• nextRunAtstring (date-time)

  Next scheduled run time in RFC 3339 format. Omitted when paused or when the trigger has no scheduled time (idle, continuous, or only after a scan).

• ownerstring

  ID of the plugin that registered the task. Omitted for core tasks.

• pausedbooleanRequired

  True if the schedule is paused.

• ruleScheduleRuleRequired
• runningbooleanRequired

  True if a run of this task kind is currently in progress, whether scheduled or started manually.

• taskScheduleTaskRequired

Collection of task schedules plus the time zone they are evaluated in.

object

• schedulesarray of ScheduleRequired

  Schedules, one per task kind.

• timeZonestringRequired

  IANA name of the server time zone; falls back to the process time zone when the server setting is blank.

Outcome of the last run: "succeeded", "failed", "cancelled", or "skipped" (the time came but nothing ran, either because there was nothing to do or a task of the same kind was already running).

string: succeeded | failed | cancelled | skipped

Desired schedule for a task kind: a trigger plus its parameters.

object

• afterScanbooleanRequired

  If true, also run after every successful full scan. Only allowed for task kinds whose allowsAfterScan is true; can be combined with any trigger.

• cronstring

  Required when trigger is "cron". Standard five-field expression (minute hour day month weekday) supporting "*", ranges, lists, "/n" steps, English abbreviations and macros such as "@daily". Seconds, years, "L", "W", "#" and "?" are not supported.

• everySecondsinteger

  Required when trigger is "interval": seconds between runs, from 300 (5 minutes) to 2678400 (31 days).

• triggerScheduleTriggerRequired
• windowScheduleWindow

Schedulable task ID. Core tasks are "library_scan" (incremental scan), "library_full_scan" (full scan), "scrape" (metadata scraping of items that are waiting), "metadata_refresh" (re-fetch provider data that has gone stale, weekly at night by default), "poster_pregenerate" (pre-generate poster images), "cleanup" (clean up temporary data), "backup" (create a backup), "database_maintenance" (online database vacuum, statistics update and index rebuild without downtime; runs weekly on Sunday 04:30 by default and also once after a library is deleted). Plugins can register their own tasks, named "pluginId.taskName" in lowercase; those appear after the core tasks while the plugin is enabled, and an unregistered task returns 404. New values may be added over time.

string

How a task is triggered: "cron" (cron expression), "interval" (fixed period after the previous start), "idle" (when the server is idle), "continuous" (always in the background, yielding while someone is playing).

string: cron | interval | idle | continuous | manual

Daily time window in server time during which a task may run, as [start, end). If end is less than start the window crosses midnight.

object

• endMinuteintegerRequired

  End of the window, in minutes since midnight (exclusive).

• startMinuteintegerRequired

  Start of the window, in minutes since midnight (inclusive).

Metadata scraping state of an item: "none" (not needed: has an NFO, cannot be scraped, or automatic scraping is off), "pending" (waiting to be scraped), "scraped" (matched automatically), "failed" (see scrapeError), "needsIdentify" (no high-confidence candidate, waiting for manual identification), "identified" (identified by a user).

string: none | pending | scraped | failed | needsIdentify | identified

A person matched by a search.

object

• idstringRequired

  Unique identifier of the person.

• imageTagstring

  Tag identifying the person's image, used for cache busting when fetching it. Absent when there is no image.

• namestringRequired

  Display name of the person.

• rolestring

  Role the person plays in the matched work, such as actor or director.

Search results: matching items and matching people.

object

• itemsarray of ItemSummaryRequired

  Items matching the query.

• peoplearray of SearchPersonRequired

  People matching the query.

Generic result of an operation that returns no data.

object

• messagestring

  Optional human-readable message about the result.

• successbooleanRequired

  True if the operation succeeded.

Kind of media stream: "Video", "Audio" or "Subtitle".

string: Video | Audio | Subtitle

Why subtitles cannot be downloaded for an item: "license_required" (no subtitle license; checked first), "no_provider" (no usable subtitle provider: not installed, not enabled or not configured), "not_writable" (the directory holding the video is not writable), "remote_readonly" (the source is a read-only remote source).

string: license_required | no_provider | not_writable | remote_readonly

Result of one health check.

object

• detailstring

  On success, a summary supplied by the check (for example the ffprobe version). On failure, a generic message; details are in the server log.

• latencyMsinteger (int64)Required

  Time the check took, in milliseconds.

• namestringRequired

  Name of the check, for example "database", "ffprobe" or "mediaRoot".

• statusstring: ok | errorRequired

  Result of the check: "ok" or "error".

Server health and runtime information.

object

• archstringRequired

  CPU architecture the server runs on, for example "amd64".

• cachesarray of CacheUsageRequired

  Disk usage of the server's caches.

• checksarray of SystemCheckRequired

  Individual health check results.

• goVersionstringRequired

  Go runtime version the server was built with.

• osstringRequired

  Operating system the server runs on, for example "linux".

• serverIdstringRequired

  Unique identifier of this server.

• serverNamestringRequired

  Display name of this server.

• startedAtstring (date-time)Required

  Time the server process started, in RFC 3339 format.

• statusstring: ok | degradedRequired

  Overall health: "ok" when every health check passes, "degraded" when any check fails.

• uptimeSecondsinteger (int64)Required

  Seconds since the server started.

• versionstringRequired

  Version string injected at build time; "dev" for development builds.

State of the server update check.

object

• availablebooleanRequired

  True if the most recently found release is newer than the running version. Always false for development builds.

• checkedAtstring (date-time)

  Time of the most recent update check, in RFC 3339 format. Omitted if never checked.

• currentstringRequired

  Version of the running server.

• enabledbooleanRequired

  True if automatic update checking is on and a release information URL is configured.

• lastErrorCodestring

  Category of the most recent failed check, such as "unreachable", "timeout", "invalid" or "unknown". Omitted when the last check did not fail.

• latestReleaseInfo

A user account.

object

• avatarTagstring

  Tag of the user's avatar, present only when an avatar exists. Fetch the image with GET /images/users/{id}?tag=.

• createdAtstring (date-time)

  Time the account was created, in RFC 3339 format.

• hasPasswordboolean

  True if a password is set.

• hasPinboolean

  True if a PIN is set.

• idstringRequired

  Unique identifier of the user.

• isAdminbooleanRequired

  True if the user is an administrator.

• lastLoginAtstring (date-time)

  Time of the user's last login, in RFC 3339 format.

• namestringRequired

  Account name.

• parentalEditableboolean

  True if the current license allows editing parental controls. When false, parental controls are read-only; rules already set are still enforced.

• pinLockedboolean

  True if PIN login is locked after too many failures (20 within 24 hours). Cleared by a successful password login or a PIN reset.

• planAccessMemberPlanAccess
• policyUserPolicy

Permissions and restrictions of a user.

object

• accessibleLibrariesarray of string

  IDs of the libraries a non-administrator can access. Administrators can always access all libraries, so this has no effect for them. Libraries not listed are invisible to the user (lists, details, images and streams return 404), and new libraries are not opened automatically. Always present in responses; on update, omit to keep the current value, send an empty array to revoke all. Unknown library IDs are ignored.

• allLibrariesboolean

  If true, the user can access all libraries, including ones added later, and accessibleLibraries is ignored (but still stored). Defaults to false. Not relevant for administrators. Always present in responses; on update, omit to keep the current value.

• allowDownloadboolean

  Whether the user may download media. Responses always carry the effective value: when not set explicitly it is true for administrators and unrestricted users and false for users under parental controls. On update, omit to keep the current value; sending the same value as the current effective one changes nothing and needs no license, while a different value requires a license that permits it.

• castDisabledboolean

  If true, the user cannot cast media to other devices. Defaults to false. Not relevant for administrators. Always present in responses; on update, omit to keep the current value. Setting it to true (or disabling the user, or removing administrator rights) revokes the user's currently valid cast authorizations.

• clearParentalboolean

  On update, true removes parental controls so the user becomes unrestricted. Sending it together with parental returns 400. Changing it requires a license that permits editing parental controls.

• contentDeletionLibrariesarray of string

  IDs of the libraries from which the user may delete content. Has no effect when deletion is already allowed for all libraries. On update, omit to keep the current value; an empty array clears it.

• enableContentDeletionboolean

  If true, the user can delete items and files in all libraries. Responses carry the effective value (true for administrators and false for others when not set). On update, omit to keep the current value. Deletion also requires the library to have allowDeletion enabled.

• isAdminbooleanRequired

  True if the user has administrator rights.

• isDisabledboolean

  True if the account is disabled.

• isHiddenboolean

  True if the user is hidden from the public login list.

• parentalParentalControls
• resetAllowDownloadboolean

  On update, true resets the download permission to its default, which depends on whether the user has parental controls. Sending it together with allowDownload returns 400. Changing it requires a license that permits it.

• sessionOnlyLoginboolean

  If true, the user must log in every time the browser is opened: web logins last only until the browser is closed, and the user cannot turn this off. Device tokens of third-party players are unaffected. Always present in responses; on update, omit to keep the current value. Turning it on revokes all of the user's existing web logins; turning it off does not revoke them, and they last until the browser closes.

Why live watching is not in the "watching" state: "network_fs" (network file system, scheduled scans only), "watch_limit" (system watch limit reached; raise fs.inotify.max_user_watches), "unknown" (other).

string: network_fs | watch_limit | unknown