Session Management

API endpoints for managing active sessions, controlling playback, and reporting session activities

Overview

The Session Management API provides endpoints for tracking active user sessions, controlling remote playback, reporting viewing activity, and managing session capabilities. Sessions represent active connections from client applications to the Jellyfin server.

Get Sessions

Retrieves a list of all active sessions on the server.

Endpoint: GET /Sessions

Authorization: Required

Query Parameters

controllableByUserId · string (UUID)

Filter by sessions that a given user is allowed to remote control

deviceId · string

Filter by specific device ID

activeWithinSeconds · integer

Filter by sessions active within the last N seconds

Response

sessions · array

Array of active session objects

Show SessionInfoDto properties

Id · string

Unique session identifier

UserId · string (UUID)

The user ID associated with this session

UserName · string

The username

Client · string

Client application name (e.g., “web”, “Android”, “iOS”)

DeviceId · string

Unique device identifier

DeviceName · string

Human-readable device name

DeviceType · string

Type of device (e.g., “Phone”, “Tablet”, “Desktop”)

ApplicationVersion · string

Version of the client application

RemoteEndPoint · string

IP address of the client

LastActivityDate · string (datetime)

Timestamp of last activity

LastPlaybackCheckIn · string (datetime)

Timestamp of last playback check-in

IsActive · boolean

Whether the session is currently active

SupportsMediaControl · boolean

Whether the session supports remote media control

SupportsRemoteControl · boolean

Whether the session supports remote control commands

NowPlayingItem · object

Currently playing item information

PlayState · object

Current playback state (position, paused, volume, etc.)

Capabilities · object

Client capabilities (supported media types, commands)

Status Codes

• 200 - Sessions returned successfully

Example Request

curl -X GET "https://your-server.com/Sessions?activeWithinSeconds=600" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

Example Response

[
  {
    "Id": "session123abc",
    "UserId": "6eec632a-9b0c-4a63-8b8e-7b7f9c3c9e8f",
    "UserName": "admin",
    "Client": "web",
    "DeviceId": "device456def",
    "DeviceName": "Chrome Browser",
    "DeviceType": "Desktop",
    "ApplicationVersion": "10.8.13",
    "RemoteEndPoint": "192.168.1.100",
    "LastActivityDate": "2026-03-05T12:45:30.000Z",
    "LastPlaybackCheckIn": "2026-03-05T12:45:25.000Z",
    "IsActive": true,
    "SupportsMediaControl": true,
    "SupportsRemoteControl": true,
    "NowPlayingItem": {
      "Name": "Example Movie",
      "Id": "movie123",
      "Type": "Movie"
    },
    "PlayState": {
      "PositionTicks": 18000000000,
      "IsPaused": false,
      "VolumeLevel": 100
    }
  }
]

---

Post Capabilities

Reports or updates the capabilities of a session/device.

Endpoint: POST /Sessions/Capabilities

Authorization: Required

Query Parameters

id · string

Session ID. If not provided, uses the current session.

playableMediaTypes · array[string]

Comma-delimited list of playable media types: “Audio”, “Video”, “Book”, “Photo”

supportedCommands · array[string]

Comma-delimited list of supported remote control commands

supportsMediaControl · boolean

Whether the device supports remote media control (default: false)

supportsPersistentIdentifier · boolean

Whether the device supports a unique identifier (default: true)

Response

Returns 204 No Content on success.

Status Codes

• 204 - Capabilities updated successfully

Example Request

curl -X POST "https://your-server.com/Sessions/Capabilities?playableMediaTypes=Video,Audio&supportsMediaControl=true&supportedCommands=Play,Pause,Stop,Seek" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Post Full Capabilities

Reports complete capabilities using a request body for more detailed configuration.

Endpoint: POST /Sessions/Capabilities/Full

Authorization: Required

Query Parameters

id · string

Session ID. If not provided, uses the current session.

Request Body

PlayableMediaTypes · array[string]

List of playable media types: [“Audio”, “Video”, “Book”, “Photo”]

SupportedCommands · array[string]

List of supported commands: [“Play”, “Pause”, “Stop”, “Seek”, “VolumeUp”, etc.]

SupportsMediaControl · boolean

Whether the session supports remote media control

SupportsPersistentIdentifier · boolean

Whether the device supports a persistent identifier

SupportsSync · boolean

Whether the client supports sync

Response

Returns 204 No Content on success.

Example Request

curl -X POST "https://your-server.com/Sessions/Capabilities/Full" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "PlayableMediaTypes": ["Video", "Audio"],
    "SupportedCommands": ["Play", "Pause", "Stop", "Seek", "VolumeUp", "VolumeDown", "Mute"],
    "SupportsMediaControl": true,
    "SupportsPersistentIdentifier": true
  }'

---

Report Viewing

Reports that a session is viewing a specific item (not playing, just viewing details).

Endpoint: POST /Sessions/Viewing

Authorization: Required

Query Parameters

sessionId · string

Session ID. If not provided, uses the current session.

itemId · string · required

The ID of the item being viewed

Response

Returns 204 No Content on success.

Status Codes

• 204 - Viewing activity reported successfully

Example Request

curl -X POST "https://your-server.com/Sessions/Viewing?itemId=movie123" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Report Session Ended (Logout)

Reports that the current session has ended and logs out the user.

Endpoint: POST /Sessions/Logout

Authorization: Required

Response

Returns 204 No Content on success. The authentication token is invalidated.

Status Codes

• 204 - Session ended successfully

Example Request

curl -X POST "https://your-server.com/Sessions/Logout" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Remote Control Commands

The following endpoints allow controlling playback on remote sessions.

Display Content

Instructs a session to browse to a specific item or view.

Endpoint: POST /Sessions/{sessionId}/Viewing

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

Query Parameters

itemType · string · required

The type of item (e.g., “Movie”, “Series”, “MusicAlbum”)

itemId · string · required

The ID of the item to display

itemName · string · required

The name of the item

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Viewing?itemType=Movie&itemId=movie123&itemName=Example%20Movie" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Play

Instructs a session to play specific items.

Endpoint: POST /Sessions/{sessionId}/Playing

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

Query Parameters

playCommand · string · required

The play command: “PlayNow”, “PlayNext”, or “PlayLast”

itemIds · array[string] · required

Comma-delimited list of item IDs to play

startPositionTicks · integer

Starting position in ticks (1 tick = 100 nanoseconds)

mediaSourceId · string

The media source ID to use

audioStreamIndex · integer

The audio stream index to play

subtitleStreamIndex · integer

The subtitle stream index to display

startIndex · integer

The index of the first item to play

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Playing?playCommand=PlayNow&itemIds=movie123&startPositionTicks=0" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Send Playstate Command

Sends playback control commands (play, pause, stop, seek) to a session.

Endpoint: POST /Sessions/{sessionId}/Playing/{command}

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

command · string · required

Playstate command: “Stop”, “Pause”, “Unpause”, “Seek”, “NextTrack”, “PreviousTrack”

Query Parameters

seekPositionTicks · integer

Position to seek to in ticks (for Seek command)

controllingUserId · string

The user ID issuing the command

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Playing/Pause" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

curl -X POST "https://your-server.com/Sessions/session123abc/Playing/Seek?seekPositionTicks=30000000000" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Send System Command

Sends system-level commands to a session.

Endpoint: POST /Sessions/{sessionId}/System/{command}

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

command · string · required

System command: “VolumeUp”, “VolumeDown”, “Mute”, “Unmute”, “ToggleMute”

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/System/VolumeUp" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Send General Command

Sends a general command to a session.

Endpoint: POST /Sessions/{sessionId}/Command/{command}

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

command · string · required

General command type (e.g., “DisplayContent”, “GoHome”, “GoToSettings”)

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Command/GoHome" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Send Full General Command

Sends a complete general command with custom parameters.

Endpoint: POST /Sessions/{sessionId}/Command

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID to control

Request Body

Name · string · required

Command name (e.g., “DisplayMessage”, “SetVolume”)

Arguments · object

Dictionary of command arguments

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Command" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "SetVolume",
    "Arguments": {
      "Volume": "50"
    }
  }'

---

Send Message

Displays a message to the user on the target session.

Endpoint: POST /Sessions/{sessionId}/Message

Authorization: Required

Path Parameters

sessionId · string · required

The target session ID

Request Body

Header · string

Message header (defaults to “Message from Server”)

Text · string · required

Message text to display

TimeoutMs · integer

How long to display the message in milliseconds

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/Message" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Header": "Server Notification",
    "Text": "Server maintenance in 10 minutes",
    "TimeoutMs": 10000
  }'

---

Multi-User Sessions

Jellyfin supports multiple users in a single session (e.g., for family viewing).

Add User to Session

Adds an additional user to an existing session.

Endpoint: POST /Sessions/{sessionId}/User/{userId}

Authorization: Required

Path Parameters

sessionId · string · required

The session ID

userId · string (UUID) · required

The user ID to add

Example Request

curl -X POST "https://your-server.com/Sessions/session123abc/User/6eec632a-9b0c-4a63-8b8e-7b7f9c3c9e8f" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Remove User from Session

Removes an additional user from a session.

Endpoint: DELETE /Sessions/{sessionId}/User/{userId}

Authorization: Required

Path Parameters

sessionId · string · required

The session ID

userId · string (UUID) · required

The user ID to remove

Example Request

curl -X DELETE "https://your-server.com/Sessions/session123abc/User/6eec632a-9b0c-4a63-8b8e-7b7f9c3c9e8f" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Authentication Providers

Get Auth Providers

Retrieves all available authentication providers.

Endpoint: GET /Auth/Providers

Authorization: Required (Administrator with elevated privileges)

Response

Returns an array of name-ID pairs for available authentication providers.

Example Request

curl -X GET "https://your-server.com/Auth/Providers" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

Example Response

[
  {
    "Name": "Default",
    "Id": "Jellyfin.Server.Implementations.Users.DefaultAuthenticationProvider"
  },
  {
    "Name": "LDAP",
    "Id": "Jellyfin.Plugin.LDAP_Authentication.LdapAuthenticationProvider"
  }
]

---

Get Password Reset Providers

Retrieves all available password reset providers.

Endpoint: GET /Auth/PasswordResetProviders

Authorization: Required (Administrator with elevated privileges)

Example Request

curl -X GET "https://your-server.com/Auth/PasswordResetProviders" \
  -H "Authorization: MediaBrowser Token=YOUR_API_TOKEN"

---

Session Concepts

Session Lifecycle

1. Creation: Session created when user authenticates
2. Capability Reporting: Client reports its capabilities
3. Activity: Client sends periodic heartbeats and activity updates
4. Termination: Session ends via logout or timeout

Ticks and Time

Jellyfin uses “ticks” for time measurements:

• 1 tick = 100 nanoseconds
• 10,000 ticks = 1 millisecond
• 10,000,000 ticks = 1 second
• 600,000,000 ticks = 1 minute

Example conversions:

• 30 seconds = 300,000,000 ticks
• 5 minutes = 3,000,000,000 ticks
• 1 hour = 36,000,000,000 ticks

Remote Control

For remote control to work:

1. Target session must report SupportsRemoteControl: true
2. Controlling user must have appropriate permissions
3. Session must be active (recent activity)

Supported Commands

Common playstate commands:

• Stop, Pause, Unpause
• Seek, NextTrack, PreviousTrack
• FastForward, Rewind

Common system commands:

• VolumeUp, VolumeDown, Mute, Unmute, ToggleMute, SetVolume

Common general commands:

• DisplayContent, GoHome, GoToSettings
• MoveUp, MoveDown, MoveLeft, MoveRight
• PageUp, PageDown, Select, Back