Jellyfin API
Official vendor OpenAPI document · agent-readyMediaVideo ProcessingapiKey387 EndpointsREST
For 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.
Use for: Search my Jellyfin library for a specific movie title, Start playing a TV episode on the living room device, List all currently active playback sessions on my Jellyfin server, Get the latest activity log entries from Jellyfin
Not supported: Does not handle media acquisition, DRM, or payments - use for managing and streaming a self-hosted Jellyfin library only.
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.
Install Jentic One Beta
Connect the Jellyfin API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Jellyfin API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fjellyfin.local%2Fjellyfin" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fjellyfin.local%2Fjellyfin" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Jellyfin API.
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
Patterns agents use Jellyfin API for, with concrete tasks.
★ 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.
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.
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.
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.
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
387 endpoints — 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.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Jellyfin API through Jentic.
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.
GET STARTED