Jellyfin Widget API Compatibility#

The Homepage Jellyfin widget supports two API modes — version 1 (default) and version 2 — to handle breaking changes across Jellyfin server releases. The core issue: Jellyfin progressively removed the legacy emby/-prefixed routes and api_key query-param authentication, requiring widget-side changes to remain compatible.

API Versioning Compatibility Matrix#

Jellyfin 10.12 first removed the legacy emby/-prefixed routes (e.g., /emby/Sessions, /emby/Items/Counts) 1. Jellyfin 12.0 completed this migration by fully eliminating all prefixed routes, causing version 1 widgets to return 404/503 errors 2 3.

Endpoint Definitions#

Both endpoint sets are defined in src/widgets/jellyfin/widget.js:

• V1 (lines 6–22): Uses emby/ prefix with api_key query param — e.g., emby/Sessions?api_key={key}, emby/Items/Counts?api_key={key}
• V2 (lines 23–39): Drops the prefix entirely — Sessions, Items/Counts — with no api_key query param (auth is header-only)

Version Branching Logic#

src/widgets/jellyfin/component.jsx lines 212–219 reads widget?.version (defaulting to 1) and maps it to the appropriate endpoint keys:

version 1 → Sessions, Count, Pause, Unpause
version 2 → SessionsV2, CountV2, PauseV2, UnpauseV2

Authentication#

src/widgets/jellyfin/proxy.js lines 29–34 constructs and sends a MediaBrowser Token Authorization header for all requests regardless of version:

MediaBrowser Token="<encoded-key>", Client="Homepage", Device="Homepage", DeviceId="<group-service>", Version="1.0.0"

The DeviceId is derived from the widget's service group and name, or from explicit widget config. This header format is accepted by both legacy (≥ 10.12) and current Jellyfin servers, making it safe to use as a universal auth mechanism.

Configuration#

Set version: 2 for any Jellyfin server ≥ 10.12. Omitting it defaults to 1, which fails on 10.12+ with 404 errors 4.

widget:
  type: jellyfin
  url: http://jellyfin.host.or.ip:port
  key: <api-key>
  version: 2 # required for Jellyfin >= 10.12 / 12.0
  enableBlocks: true # optional, defaults to false
  enableNowPlaying: true
  enableUser: true
  enableMediaControl: false
  showEpisodeNumber: true
  expandOneStreamToTwoRows: false

Full option reference: Jellyfin widget docs.

Key Source Files#

Related Issues & Discussions#

• Discussion #6122 — Original tracking issue for Jellyfin 10.12 emby/ route removal 1
• Issue #7113 — 503 errors on Jellyfin 12.0; fix is version: 2 2
• Discussion #7112 — Feature request for Jellyfin 12.x support; resolved by pointing to version: 2 3
• Discussion #7122 — 404 errors on Jellyfin v12 widget 5