canonical: https://jentic.com/apis/jellyfin.local/jellyfin

# Jellyfin API

The Jellyfin API is the HTTP control surface for Jellyfin, the free open-source media server that organizes and streams personal libraries of movies, TV, music, books, and live TV. With 387 endpoints, the API covers library management, item playback, user and access-key administration, transcoding, subtitles, channels, plugins, scheduled tasks, and device sync. Because Jellyfin runs on the user's own hardware, the base URL is the operator's local server (e.g. http://localhost:8096), not a hosted SaaS endpoint, and authentication is a server-issued API key sent via the X-Emby-Authorization or X-Emby-Token header. The spec mirrors Jellyfin 10.7 stable.

## For AI agents

Drive a self-hosted Jellyfin media server: browse libraries, search items, start and control playback sessions, manage users and API keys, and trigger transcoding or library scans.

## Scope

Does not handle media acquisition, DRM, or payments - use for managing and streaming a self-hosted Jellyfin library only.

## Capabilities

- Search and browse personal media libraries across movies, TV episodes, music, audiobooks, and photos
- Start and stop playback sessions on connected client devices via /Sessions endpoints
- Issue, list, and revoke server API keys through `/Auth/Keys` for headless integrations
- Stream or transcode audio and video on demand via `/Audio/{itemId}/stream` and the equivalent video routes
- Manage users, library access, and parental controls via the Users tag endpoints
- Trigger library scans, scheduled tasks, and plugin operations from the System and ScheduledTasks routes
- Read activity-log entries for auditing playback and admin actions

## Use cases

### Voice or Chat Control of a Home Media Server

A home assistant agent receives natural-language commands like 'play the next episode of Andor in the bedroom' and translates them to Jellyfin API calls: search the library for the show, find the next unwatched episode, and POST to `/Sessions/{sessionId}/Playing` to begin playback on the named device. The 387-endpoint surface covers every step end-to-end without scraping the web UI.

Example prompt: Search /Items for 'Andor', find the next episode where UserData.Played is false, and POST to `/Sessions/{sessionId}/Playing` with the resolved itemId to start playback on the user's bedroom client.

### Library Audit and Cleanup Automation

An admin agent walks the library to find duplicates, missing metadata, or low-bitrate files. Listing items with filters, reading their metadata, and triggering targeted library refreshes via /ScheduledTasks lets a maintenance script keep a multi-terabyte library tidy without opening the dashboard. Useful for collections with tens of thousands of items.

Example prompt: List /Items with IncludeItemTypes=Movie, group by Name+ProductionYear, and report any group with more than one Path along with file sizes for a human to choose what to delete.

### Headless Backup and Sync Client

A scheduled job creates a dedicated API key via `/Auth/Keys`, then walks /Items to enumerate the library and downloads selected items at the original quality from `/Items/{id}/Download.` The dedicated key can be revoked the moment the backup completes, isolating risk from the user's main credentials.

Example prompt: POST `/Auth/Keys` with App=BackupBot, walk /Items filtered by IsFavorite=true to download each via `/Items/{id}/Download`, then DELETE `/Auth/Keys/{key}` when finished.

### AI Agent Integration via Jentic

An AI media-control agent uses Jentic to discover Jellyfin operations by intent. Because the Jellyfin instance lives on the user's LAN, Jentic stores the user-supplied base URL and API key together so the agent can target the right server without ever holding the raw token in its prompt context.

Example prompt: Search Jentic for 'play media on my jellyfin server', load the GetItems and Play schemas, and execute them in sequence to start playback for the user's request.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/Items` | Search and filter all media items across libraries |
| GET | `/Sessions` | List active playback sessions |
| POST | `/Sessions/{sessionId}/Playing` | Start playback of an item on a session |
| GET | `/Auth/Keys` | List server API keys |
| POST | `/Auth/Keys` | Issue a new API key |
| GET | `/Users` | List all users on the server |

## Key resources

- **Items** — Search, browse, and stream every media item across libraries.
- **Sessions** — List active client sessions and send playback commands (play, pause, seek).
- **Users** — Create and manage user accounts and library access policies.
- **Auth/Keys** — Issue and revoke server API keys for headless clients.
- **ScheduledTasks** — Inspect and trigger library scans and other maintenance tasks.

## Why Jentic

- **Setup:** Wiring the Jellyfin API by hand means pointing at each self-hosted server's own base URL and API key and working across hundreds of endpoints yourself. Through Jentic you install once, import Jellyfin from the API Directory, store the server URL and key once, and your agent calls it.
- **Permission scoping:** Jellyfin exposes both library reads and control operations, so scope by operation: allow the agent only what it needs, such as listing items and sessions or starting playback, and leave API-key management out unless you add it. You pick the allowed set, so it stays within managing and streaming your own library.
- **Credential handling:** Your Jellyfin base URL and API key are stored once together, encrypted, by your own Jentic One instance and injected at execution time. The key never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'play a movie on my home media server', and Jentic returns the matching Jellyfin Sessions and Items operations with their input schemas so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Plex API** — Plex offers a similar self-hosted media server with a cloud-mediated authentication layer rather than Jellyfin's pure-local model
- **Anthropic Messages API** — Use Claude alongside Jellyfin to interpret natural-language playback requests and pick the right item

## FAQ

### What authentication does the Jellyfin API use?

Jellyfin uses a server-issued API key sent in the X-Emby-Authorization or X-Emby-Token header (the spec models this as the CustomAuthentication scheme). Keys are minted at `/Auth/Keys` by an authenticated admin. Through Jentic, the key plus the user's base URL are stored together in the vault so the agent never sees the raw token.

### Can I start media playback on a specific device with the Jellyfin API?

Yes. Call GET /Sessions to list active client sessions, find the one whose DeviceName matches the target device, then POST to `/Sessions/{sessionId}/Playing` with the item ID. Jellyfin pushes the play command to that client.

### What are the rate limits for the Jellyfin API?

Jellyfin runs on the user's own hardware so there are no provider-side rate limits - only the limits of the host machine and network. For library walks, page through /Items with StartIndex and Limit (default page sizes around 100) rather than requesting everything at once.

### How do I search the library and play a result through Jentic?

Run pip install jentic, search for 'play media on my jellyfin server', then load and execute the GetItems operation with SearchTerm set to the title. Take the first matching Id, then load and execute the Play session command with that itemId.

### Does the Jellyfin API need a hosted base URL or is it local?

Jellyfin is self-hosted, so the base URL is the operator's own server address - typically http://localhost:8096 on the host or a LAN/VPN address from another machine. The spec uses http://localhost as a placeholder; replace it with your real Jellyfin URL when calling.

### Is the Jellyfin API free?

Yes - Jellyfin is free and open source under the GPLv2 license. Run your own server and the full 387-endpoint API is available with no subscription.

### Can I limit what my agent is allowed to do with the Jellyfin API?

Yes. Because you run Jentic One yourself, your own rules decide which Jellyfin operations the agent may call, so you scope access at the operation level. You can allow read and playback operations such as listing items via GET /Items, listing sessions via GET /Sessions, and starting playback via POST `/Sessions/{sessionId}/Playing`, while leaving API-key management on `/Auth/Keys` and user administration on /Users out of the allowed set. Your server URL and API key are held by your own Jentic One instance and injected only for the operations you permit, keeping the agent within managing and streaming your own library.