API Overview - Jellyfin Server

Jellyfin Server provides a comprehensive REST API for managing and accessing media content, user data, and server configuration.

API Architecture

The Jellyfin API is built using ASP.NET Core and follows RESTful principles:

Framework: ASP.NET Core with Kestrel web server
API Documentation: Swagger/OpenAPI 3.0
Authentication: Custom authentication scheme with API keys and user tokens
Response Format: JSON (primary), XML (supported)
Base URL: http://localhost:8096 (default)

Project Structure

The API implementation is organized across several projects:

Project	Purpose
`Jellyfin.Api`	API controllers, models, and middleware
`MediaBrowser.Controller`	Core interfaces and business logic contracts
`MediaBrowser.Model`	Shared DTOs and data models
`Emby.Server.Implementations`	Core business logic implementations

API Documentation

Jellyfin provides interactive API documentation through Swagger UI:

Start the Jellyfin Server

Run the server locally (see Building from Source).

Access Swagger UI

Navigate to: http://localhost:8096/api-docs/swagger/index.html

Explore and Test Endpoints

Use the interactive documentation to:

Browse all available endpoints
View request/response schemas
Test endpoints directly from your browser

ReDoc documentation is also available at: http://localhost:8096/api-docs/redoc/index.html

Authentication

The Jellyfin API uses a custom authentication scheme defined in the Jellyfin.Api/Constants/AuthenticationSchemes.cs file.

Authentication Methods

API Key
User Token
Username/Password

API keys provide full administrative access without user context.

curl -H "X-Emby-Authorization: MediaBrowser Token=\"YOUR_API_KEY\"" \
  http://localhost:8096/System/Info

API keys can be created in the Jellyfin web interface under Dashboard > API Keys.

User tokens authenticate as a specific user with their permissions.

curl -H "X-Emby-Authorization: MediaBrowser Client=\"MyApp\", Device=\"MyDevice\", Token=\"USER_TOKEN\"" \
  http://localhost:8096/Users/Me

Authenticate to obtain a user token:

curl -X POST http://localhost:8096/Users/AuthenticateByName \
  -H "Content-Type: application/json" \
  -H "X-Emby-Authorization: MediaBrowser Client=\"MyApp\", Device=\"MyDevice\", DeviceId=\"12345\", Version=\"1.0.0\"" \
  -d '{
    "Username": "admin",
    "Pw": "password"
  }'

Authorization Header Format

The custom authorization header has the following format:

X-Emby-Authorization: MediaBrowser Client="ClientName", Device="DeviceName", DeviceId="UniqueDeviceId", Version="1.0.0", Token="AccessToken"

The authentication scheme is named CustomAuthentication internally and is configured in Jellyfin.Server/Startup.cs.

Core API Controllers

Here are the main API controllers in Jellyfin.Api/Controllers/:

Media Management

ItemsController

Route: /ItemsQuery and retrieve media items with extensive filtering options:

Search media library
Filter by type, genre, year, etc.
Pagination and sorting
Resume points and play state

LibraryController

Route: /LibraryManage library content:

Get similar items
Get media folders
Get physical paths
Refresh metadata

VideosController

Route: /VideosVideo-specific operations:

Get additional parts
Delete alternate sources
Merge versions

AudioController

Route: /AudioAudio streaming and management:

Stream audio files
Get audio stream info
Universal audio endpoint

User Management

UserController

Route: /UsersUser account operations (see Jellyfin.Api/Controllers/UserController.cs):

List users
Create/update/delete users
User preferences
Authentication

UserLibraryController

Route: /Users/{userId}/ItemsUser-specific library operations:

Get user’s items
Mark as favorite
User ratings

PlaystateController

Route: /PlaystateTrack playback state:

Mark as played/unplayed
Update play position
Report playback progress

System & Configuration

SystemController

Route: /SystemSystem information and operations (see Jellyfin.Api/Controllers/SystemController.cs):

Get system info
Server endpoints
Restart/shutdown

ConfigurationController

Route: /ConfigurationServer configuration:

Get/update server config
Media encoding settings
Network configuration

PluginsController

Route: /PluginsPlugin management (see Jellyfin.Api/Controllers/PluginsController.cs):

List installed plugins
Enable/disable plugins
Plugin configuration
Uninstall plugins

Media Streaming

DynamicHlsController

Route: /Videos/{itemId}/master.m3u8HLS adaptive streaming:

Generate HLS playlists
Transcode on-the-fly
Multiple quality levels

SubtitleController

Route: /SubtitlesSubtitle operations:

Get subtitle streams
Search for subtitles
Upload subtitles

Common API Patterns

Dependency Injection

Controllers use constructor injection for dependencies:

Jellyfin.Api/Controllers/UserController.cs

public class UserController : BaseJellyfinApiController
{
    private readonly IUserManager _userManager;
    private readonly ISessionManager _sessionManager;
    private readonly ILogger _logger;

    public UserController(
        IUserManager userManager,
        ISessionManager sessionManager,
        ILogger<UserController> logger)
    {
        _userManager = userManager;
        _sessionManager = sessionManager;
        _logger = logger;
    }
}

Authorization Policies

Endpoints use policy-based authorization:

// Requires admin privileges
[Authorize(Policy = Policies.RequiresElevation)]
public class PluginsController : BaseJellyfinApiController
{
    // ...
}

// Available during first-time setup
[Authorize(Policy = Policies.FirstTimeSetupOrIgnoreParentalControl)]
public ActionResult<SystemInfo> GetSystemInfo()
{
    // ...
}

Common policies defined in Jellyfin.Api/Constants/Policies.cs:

RequiresElevation - Admin only
DefaultAuthorization - Any authenticated user
FirstTimeSetupOrIgnoreParentalControl - Setup or unrestricted

Response Types

Controllers return strongly-typed responses:

[HttpGet]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<PluginInfo> GetPlugin([FromRoute, Required] Guid pluginId)
{
    var plugin = _pluginManager.GetPlugin(pluginId);
    if (plugin is null)
    {
        return NotFound();
    }
    
    return plugin.GetPluginInfo();
}

Query Parameters

Use model binding for complex queries:

[HttpGet]
public ActionResult<IEnumerable<UserDto>> GetUsers(
    [FromQuery] bool? isHidden,
    [FromQuery] bool? isDisabled)
{
    var users = Get(isHidden, isDisabled, false, false);
    return Ok(users);
}

Making API Requests

Example: Get System Info

curl -H "X-Emby-Authorization: MediaBrowser Token=\"YOUR_API_KEY\"" \
  http://localhost:8096/System/Info

Example: Query Media Items

curl -X GET "http://localhost:8096/Items?userId=USER_ID&includeItemTypes=Movie&limit=10" \
  -H "X-Emby-Authorization: MediaBrowser Token=\"YOUR_API_KEY\""

Example: Update Plugin Configuration

cURL

curl -X POST "http://localhost:8096/Plugins/{pluginId}/Configuration" \
  -H "Content-Type: application/json" \
  -H "X-Emby-Authorization: MediaBrowser Token=\"YOUR_API_KEY\"" \
  -d '{
    "ApiKey": "new-api-key",
    "Enabled": true
  }'

WebSocket API

Jellyfin also provides real-time updates via WebSocket connections for:

Library updates
Playback sessions
Plugin installation progress
System messages

WebSocket messages are defined in MediaBrowser.Controller/Net/WebSocketMessages/.

Connect to the WebSocket endpoint at ws://localhost:8096/socket with proper authentication.

API Best Practices

Use API Keys for Services

For server-to-server integrations, use API keys rather than user credentials.

Implement Pagination

Always use startIndex and limit parameters when querying large datasets.

Cache Responses

Cache static data like system info and library structure to reduce API calls.

Handle Rate Limits

Implement exponential backoff for failed requests and respect server limits.

Extending the API

To add new API endpoints:

Create a Controller

Add a new controller in Jellyfin.Api/Controllers/:

namespace Jellyfin.Api.Controllers;

[Authorize]
public class MyCustomController : BaseJellyfinApiController
{
    [HttpGet("MyEndpoint")]
    public ActionResult<MyResponse> GetData()
    {
        return Ok(new MyResponse());
    }
}

Add Response Models

Define DTOs in MediaBrowser.Model/ or Jellyfin.Api/Models/.

Implement Business Logic

Use interfaces from MediaBrowser.Controller/ and implementations from Emby.Server.Implementations/.

Test Your Endpoint

Write tests in tests/Jellyfin.Api.Tests/Controllers/.

Next Steps

Plugin Development

Create plugins that extend the Jellyfin API

Contributing Guide

Learn how to contribute API changes to Jellyfin

Building from Source

Set up your development environment

API Documentation

Explore the interactive API documentation

Getting Started

Core Concepts

Server Setup

Development

​API Architecture

​Project Structure

​API Documentation

​Authentication

​Authentication Methods

​Authorization Header Format

​Core API Controllers

​Media Management

ItemsController

LibraryController

VideosController

AudioController

​User Management

UserController

UserLibraryController

PlaystateController

​System & Configuration

SystemController

ConfigurationController

PluginsController

​Media Streaming

DynamicHlsController

SubtitleController

​Common API Patterns

​Dependency Injection

​Authorization Policies

​Response Types

​Query Parameters

​Making API Requests

​Example: Get System Info

​Example: Query Media Items

​Example: Update Plugin Configuration

​WebSocket API

​API Best Practices

Use API Keys for Services

Implement Pagination

Cache Responses

Handle Rate Limits

​Extending the API

​Next Steps

Plugin Development

Contributing Guide

Building from Source

API Documentation

API Architecture

Project Structure

API Documentation

Authentication

Authentication Methods

Authorization Header Format

Core API Controllers

Media Management

User Management

System & Configuration

Media Streaming

Common API Patterns

Dependency Injection

Authorization Policies

Response Types

Query Parameters

Making API Requests

Example: Get System Info

Example: Query Media Items

Example: Update Plugin Configuration

WebSocket API

API Best Practices

Extending the API

Next Steps