Skip to content

Jellyfin — Reference

  • Website: https://jellyfin.org
  • API docs: https://api.jellyfin.org
  • Swagger (local): http://192.168.1.114:8096/api-docs/swagger/index.html
  • GitHub: https://github.com/jellyfin/jellyfin
  • Plugin repos: https://jellyfin.org/docs/general/server/plugins/

Authentication

API requests use an API key (generated in Dashboard → API Keys) via the Authorization header.

# API key auth
curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/...

API key stored in Vault at secret/jellyfin → api_key.

API — System

Health check

curl -s http://192.168.1.114:8096/health   # returns "Healthy"

Server info

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/System/Info | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(f'v{d[\"Version\"]} OS={d[\"OperatingSystem\"]}')"

Restart server

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/System/Restart

Shutdown server

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/System/Shutdown

API — Libraries

List all libraries

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Library/VirtualFolders | python3 -c \
  "import json,sys; [print(f'{l[\"Name\"]} type={l[\"CollectionType\"]} paths={l[\"Locations\"]}') for l in json.load(sys.stdin)]"

Trigger library scan

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Library/Refresh

Scan a specific library

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  "http://192.168.1.114:8096/Items/<library-id>/Refresh"

API — Items (Media)

Search items

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  "http://192.168.1.114:8096/Items?searchTerm=Naruto&recursive=true&limit=10" | python3 -c \
  "import json,sys; [print(f'{i[\"Id\"]} {i[\"Name\"]} ({i[\"Type\"]})') for i in json.load(sys.stdin)['Items']]"

Get item details

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Items/<item-id>

Get recently added

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  "http://192.168.1.114:8096/Items/Latest?limit=10"

API — Users

List users

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Users | python3 -c \
  "import json,sys; [print(f'{u[\"Id\"]} {u[\"Name\"]} admin={u[\"Policy\"][\"IsAdministrator\"]}') for u in json.load(sys.stdin)]"

Update user policy (e.g., set auth provider for SSO)

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  -H "Content-Type: application/json" \
  http://192.168.1.114:8096/Users/<user-id>/Policy \
  -d '{"AuthenticationProviderId": "Jellyfin.Plugin.SSO.SSOAuthenticationProviderPlugin", "IsAdministrator": true}'

API — Branding (Themes & SSO Button)

Set custom CSS and login button

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  -H "Content-Type: application/json" \
  http://192.168.1.114:8096/System/Configuration/branding \
  -d '{
    "CustomCss": "<css content>",
    "LoginDisclaimer": "<html for SSO button>"
  }'

API — Plugins

List installed plugins

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Plugins | python3 -c \
  "import json,sys; [print(f'{p[\"Name\"]} v{p[\"Version\"]} id={p[\"Id\"]}') for p in json.load(sys.stdin)]"

Configure a plugin (e.g., SSO-Auth)

curl -s -X POST -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  -H "Content-Type: application/json" \
  http://192.168.1.114:8096/Plugins/505ce9d1-d916-42fa-86ca-673ef241d7df/Configuration \
  -d '<plugin config JSON>'

SSO-Auth plugin GUID: 505ce9d1-d916-42fa-86ca-673ef241d7df

API — Sessions & Devices

List active sessions

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Sessions | python3 -c \
  "import json,sys; [print(f'{s[\"DeviceName\"]} user={s.get(\"UserName\",\"?\")} client={s[\"Client\"]}') for s in json.load(sys.stdin)]"

List registered devices

curl -s -H "Authorization: MediaBrowser Token=$JELLYFIN_API_KEY" \
  http://192.168.1.114:8096/Devices

What the API/CLI Cannot Do

Gap Workaround
Cannot configure transcoding settings via API Use web UI: Dashboard → Playback → Transcoding
Cannot install plugins via API (only add repos + install on restart) Playbook adds repo URL, installs on next restart
Cannot manage QuickConnect authorizations via API Use web UI: Dashboard → Devices
Cannot configure library paths via API Use web UI: Dashboard → Libraries
No CLI — API only Use curl with API key
Cannot trigger metadata refresh for a single item via simple POST Use POST /Items/{id}/Refresh with query params for specific providers
Cannot stream/transcode via API (designed for client apps) Use Jellyfin clients or web UI for playback
Mobile apps don't support SSO Use QuickConnect for mobile/TV/desktop clients