Media Sources API: Add and Manage Plex, Jellyfin, and Emby

Media sources are the connections Tunarr maintains to your media servers—Plex, Jellyfin, Emby, or local file paths. Once connected, Tunarr scans each source’s libraries and indexes the programs available for scheduling. The Media Sources API lets you add, inspect, update, and remove sources, manage individual library settings, and monitor scan progress.

List Media Sources

Returns all configured media sources. Access tokens are not included in the response for security.

GET /api/media-sources

Response 200 — array of MediaSourceSettings objects.

string (uuid)

Unique identifier for the media source.

name

string

Display name of the media source.

type

string

Source type: plex | jellyfin | emby | local.

uri

string

Base URL of the media server (Plex/Jellyfin/Emby only).

username

string

Username used to connect (Plex/Jellyfin/Emby only).

libraries

array

Known libraries within this source, each with id, name, type, enabled, lastScannedAt, isLocked, and mediaType.

pathReplacements

array

List of { localPath, serverPath } pairs for path-rewriting (remote media sources).

sendGuideUpdates

boolean

Whether the source sends guide updates automatically.

curl http://localhost:8000/api/media-sources

Get Media Source

Returns a single media source by its UUID.

GET /api/media-sources/:mediaSourceId

mediaSourceId

string (uuid)

required

UUID of the media source.

Response 200 — MediaSourceSettings object. Response 404 — media source not found.

curl http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001

Add Media Source

Registers a new media source. For remote sources (Plex, Jellyfin, Emby) provide the server URL and access token. For local sources provide one or more filesystem paths.

POST /api/media-sources

type

string

required

plex | jellyfin | emby | local.

name

string

required

A human-readable label for this source.

uri

string

Base URL of the media server (required for plex, jellyfin, emby).

accessToken

string

API/access token for authentication (required for plex, jellyfin, emby).

username

string

Username associated with the access token.

paths

array of strings

Filesystem paths (required for local type, e.g. ["/media/movies"]).

sendGuideUpdates

boolean

Enable automatic guide updates from this source.

Response 201 — { "id": "<new-uuid>" }. Response 500 — server error (e.g. duplicate name, unreachable server).

curl -X POST http://localhost:8000/api/media-sources \
  -H "Content-Type: application/json" \
  -d '{
    "type": "jellyfin",
    "name": "Home Jellyfin",
    "uri": "http://192.168.1.100:8096",
    "accessToken": "abc123tokenhere",
    "username": "admin",
    "sendGuideUpdates": true
  }'

Update Media Source

Replaces the configuration of an existing media source. For local sources, updating triggers an immediate re-scan.

PUT /api/media-sources/:id

string (uuid)

required

UUID of the media source to update.

Request body — an UpdateMediaSourceRequest object with the same fields as Add Media Source plus the required id field. Response 200 — success (no body). Response 500 — server error.

curl -X PUT http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "id": "d4e5f6a7-0000-0000-0000-000000000001",
    "type": "jellyfin",
    "name": "Home Jellyfin (Updated)",
    "uri": "http://192.168.1.100:8096",
    "accessToken": "newtokenhere",
    "username": "admin"
  }'

Delete Media Source

Removes a media source and regenerates the XMLTV guide to drop programs from that source.

DELETE /api/media-sources/:id

string (uuid)

required

UUID of the media source to delete.

Response 200 — source deleted. Response 500 — deletion failed.

curl -X DELETE http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001

List Libraries for a Media Source

Returns all libraries (sections) discovered within a media source.

GET /api/media-sources/:id/libraries

string (uuid)

required

UUID of the media source.

Response 200 — array of MediaSourceLibrary objects.

string (uuid)

Library UUID.

name

string

Library name as reported by the media server.

type

string

Source type inherited from the parent media source.

mediaType

string

Content type: movie, show, music, etc.

enabled

boolean

Whether Tunarr actively syncs this library.

lastScannedAt

number

Epoch timestamp of the last successful scan (milliseconds).

isLocked

boolean

true when a scan is currently in progress.

externalKey

string

The library’s key or ID as reported by the upstream media server.

Response 400 — cannot list libraries for a local source. Response 404 — media source not found.

curl http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001/libraries

Update Library

Enables or disables a specific library within a media source. Enabling triggers an immediate background scan.

PUT /api/media-sources/:id/libraries/:libraryId

string (uuid)

required

UUID of the media source.

libraryId

string

required

UUID of the library to update.

enabled

boolean

required

Set true to enable the library and schedule it for scanning, false to disable it.

Response 200 — updated MediaSourceLibrary object. Response 400 — operation not supported (e.g. local source). Response 404 — source or library not found.

curl -X PUT \
  http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001/libraries/lib-uuid-here \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Refresh Libraries

Triggers a discovery pass that detects newly-added or removed libraries on the media source without performing a full content scan.

POST /api/media-sources/:id/libraries/refresh

string (uuid)

required

UUID of the media source.

Response 200 — refresh enqueued. Response 404 — media source not found.

Scan a Library

Triggers a content scan of one or all enabled libraries in a media source. The scan runs asynchronously.

POST /api/media-sources/:id/libraries/:libraryId/scan

string (uuid)

required

UUID of the media source.

libraryId

string

required

UUID of the library to scan, or the special value "all" to scan every enabled library.

forceScan

boolean

When true, rescan even items that have not changed since the last scan.

Response 202 — scan scheduled. Response 404 — source not found.

# Scan all enabled libraries for a source
curl -X POST \
  "http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001/libraries/all/scan"

# Force-rescan a specific library
curl -X POST \
  "http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001/libraries/lib-uuid-here/scan?forceScan=true"

Get Media Source Health Status

Pings the upstream media server and returns whether it is reachable. Times out after 60 seconds.

GET /api/media-sources/:id/status

string (uuid)

required

UUID of the media source.

Response 200 — { "healthy": true } or { "healthy": false, "status": "unreachable" | "timeout" }. Response 404 — source not found.

curl http://localhost:8000/api/media-sources/d4e5f6a7-0000-0000-0000-000000000001/status

Check Foreign Source Status

Tests reachability for a media server that has not been saved to Tunarr yet. Useful for validating credentials before calling Add Media Source.

POST /api/media-sources/foreignstatus

type

string

required

plex | jellyfin | emby | local.

uri

string

Server URL (required for plex, jellyfin, emby).

accessToken

string

Access token to test (required for plex, jellyfin, emby).

paths

array of strings

Filesystem paths to check (required for local).

Response 200 — { "healthy": true } or { "healthy": false, "status": "unreachable" | "timeout" }.

curl -X POST http://localhost:8000/api/media-sources/foreignstatus \
  -H "Content-Type: application/json" \
  -d '{
    "type": "plex",
    "uri": "http://192.168.1.50:32400",
    "accessToken": "my-plex-token"
  }'

Get Library by ID

Retrieves a single library record along with its parent media source details. Accepts the library UUID directly without needing the media source UUID.

GET /api/media-libraries/:libraryId

libraryId

string (uuid)

required

UUID of the library.

Response 200 — MediaSourceLibrary with an embedded mediaSource field. Response 404 — library not found.

Get Library Programs

Returns all content programs indexed from a specific library.

GET /api/media-libraries/:libraryId/programs

libraryId

string (uuid)

required

UUID of the library.

Response 200 — array of ContentProgram objects. Response 404 — library not found.

Overview

Endpoints

Media Sources API: Add and Manage Plex, Jellyfin, and Emby

List Media Sources

Get Media Source

Add Media Source

Update Media Source

Delete Media Source

List Libraries for a Media Source

Update Library

Refresh Libraries

Scan a Library

Get Media Source Health Status

Check Foreign Source Status

Get Library by ID

Get Library Programs

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​List Media Sources

​Get Media Source

​Add Media Source

​Update Media Source

​Delete Media Source

​List Libraries for a Media Source

​Update Library

​Refresh Libraries

​Scan a Library

​Get Media Source Health Status

​Check Foreign Source Status

​Get Library by ID

​Get Library Programs

Build docs developers (and LLMs) love

List Media Sources

Get Media Source

Add Media Source

Update Media Source

Delete Media Source

List Libraries for a Media Source

Update Library

Refresh Libraries

Scan a Library

Get Media Source Health Status

Check Foreign Source Status

Get Library by ID

Get Library Programs