Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chrisbenincasa/tunarr/llms.txt

Use this file to discover all available pages before exploring further.

Tunarr’s Library consists of two special content containers: Filler Lists and Custom Shows. Filler lists are pools of short clips (bumpers, ads, interstitials) that Tunarr automatically inserts when a channel has dead air between programs. Custom shows are user-defined collections of content that behave like a playlist and can optionally sync from an external media server playlist. Both can be referenced by multiple channels simultaneously.

​
Filler Lists

​
List Filler Lists

Returns a summary of every filler list. 
GET /api/filler-lists
Response 200 — array of filler list summary objects.
​
id
string (uuid)
Filler list UUID.
​
name
string
Display name.
​
contentCount
integer
Number of programs in the filler list.
curl http://localhost:8000/api/filler-lists

​
Get Filler List

Returns a single filler list by UUID. 
GET /api/filler-lists/:id
​
id
string (uuid)
required
Filler list UUID.
Response 200 — filler list object with id, name, and contentCount. Response 404 — filler list not found. 
curl http://localhost:8000/api/filler-lists/f1e2d3c4-0000-0000-0000-000000000001

​
Create Filler List

Creates a new filler list, optionally pre-populated with programs. 
POST /api/filler-lists
​
name
string
required
Display name for the filler list.
​
programs
array
Initial set of program references to add to the list.
Response 201 — { "id": "<new-uuid>" }. 
curl -X POST http://localhost:8000/api/filler-lists \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Classic Bumpers",
    "programs": []
  }'

​
Update Filler List

Replaces the name and/or programs of an existing filler list. 
PUT /api/filler-lists/:id
​
id
string (uuid)
required
Filler list UUID.
​
name
string
Updated display name.
​
programs
array
Replacement list of program references.
Response 200 — updated filler list object (id, name, contentCount). Response 404 — filler list not found. 
curl -X PUT http://localhost:8000/api/filler-lists/f1e2d3c4-0000-0000-0000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Classic Bumpers (Updated)",
    "programs": [
      { "type": "content", "id": "e7f8a9b0-0000-0000-0000-000000000010" }
    ]
  }'

​
Delete Filler List

Permanently removes a filler list. Any channels referencing this list will no longer have it as a filler source. 
DELETE /api/filler-lists/:id
​
id
string (uuid)
required
Filler list UUID.
Response 200 — deleted. Response 404 — filler list not found. 
curl -X DELETE http://localhost:8000/api/filler-lists/f1e2d3c4-0000-0000-0000-000000000001

​
Get Filler List Programs

Returns the full content of a filler list as an array of materialized ContentProgram objects. 
GET /api/filler-lists/:id/programs
​
id
string (uuid)
required
Filler list UUID.
Response 200 — FillerListProgramming — array of ContentProgram objects. Response 404 — filler list not found.
​
uuid
string (uuid)
Program UUID.
​
type
string
movie | episode | track | music_video | other_video.
​
title
string
Program title.
​
duration
number
Duration in milliseconds.
​
sourceType
string
plex | jellyfin | emby | local.
curl http://localhost:8000/api/filler-lists/f1e2d3c4-0000-0000-0000-000000000001/programs

​
Custom Shows

Custom shows are ad-hoc ordered playlists of any content from Tunarr’s program library. They can also be linked to an external media server playlist to auto-sync their contents.

​
List Custom Shows

Returns all custom shows with summary statistics. 
GET /api/custom-shows
Response 200 — array of CustomShow objects.
​
id
string (uuid)
Custom show UUID.
​
name
string
Display name.
​
contentCount
integer
Number of programs in the show.
​
totalDuration
number
Total runtime of all programs in milliseconds.
​
syncMediaSourceId
string (uuid)
Media source UUID used for external playlist sync (if configured).
​
syncMediaSourceType
string
Source type for sync: plex | jellyfin | emby.
​
syncExternalPlaylistId
string
External playlist ID for sync.
​
lastSyncedAt
number
Epoch timestamp (ms) of the last successful sync.
​
isSyncing
boolean
true when a sync is currently in progress.
curl http://localhost:8000/api/custom-shows

​
Get Custom Show

Returns a single custom show by UUID. 
GET /api/custom-shows/:id
​
id
string (uuid)
required
Custom show UUID.
Response 200 — CustomShow object. Response 404 — custom show not found. 
curl http://localhost:8000/api/custom-shows/c9d8e7f6-0000-0000-0000-000000000002

​
Create Custom Show

Creates a new custom show, optionally linked to an external playlist for automatic sync. 
POST /api/custom-shows
​
name
string
required
Display name for the custom show.
​
programs
array
Initial ordered list of program references. Each entry should identify a program by its Tunarr UUID.
​
syncMediaSourceId
string (uuid)
UUID of the media source that hosts the external playlist (optional).
​
syncExternalPlaylistId
string
External playlist ID on the media server to sync from (optional). When provided together with syncMediaSourceId, an immediate sync is triggered after creation.
Response 201 — the newly created CustomShow object (same fields as Get Custom Show). 
curl -X POST http://localhost:8000/api/custom-shows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "90s Action Classics",
    "programs": [
      { "type": "content", "id": "e7f8a9b0-0000-0000-0000-000000000005" },
      { "type": "content", "id": "b1c2d3e4-0000-0000-0000-000000000007" }
    ]
  }'

​
Update Custom Show

Replaces the content and metadata of an existing custom show. 
PUT /api/custom-shows/:id
​
id
string (uuid)
required
Custom show UUID.
​
name
string
Updated display name.
​
programs
array
Replacement ordered list of program references.
Response 200 — updated CustomShow object. Response 404 — custom show not found. 
curl -X PUT http://localhost:8000/api/custom-shows/c9d8e7f6-0000-0000-0000-000000000002 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "90s Action Classics (Extended Cut)",
    "programs": [
      { "type": "content", "id": "e7f8a9b0-0000-0000-0000-000000000005" }
    ]
  }'

​
Delete Custom Show

Permanently removes a custom show. 
DELETE /api/custom-shows/:id
​
id
string (uuid)
required
Custom show UUID.
Response 200 — { "id": "<deleted-uuid>" }. Response 404 — custom show not found. 
curl -X DELETE http://localhost:8000/api/custom-shows/c9d8e7f6-0000-0000-0000-000000000002

​
Get Custom Show Programs

Returns the ordered content of a custom show as an array of CustomProgram objects. Each entry wraps a ContentProgram with positional metadata. 
GET /api/custom-shows/:id/programs
​
id
string (uuid)
required
Custom show UUID.
Response 200 — array of CustomProgram objects.
​
id
string (uuid)
Program UUID (same as the underlying content program).
​
type
string
Always "custom".
​
customShowId
string (uuid)
UUID of the owning custom show.
​
index
integer
Zero-based position in the show’s ordered list.
​
duration
number
Duration in milliseconds.
​
program
object
The full ContentProgram object.
​
persisted
boolean
Always true for saved programs.
Response 404 — custom show not found. 
curl http://localhost:8000/api/custom-shows/c9d8e7f6-0000-0000-0000-000000000002/programs

​
Sync Custom Show

Triggers an immediate sync of a custom show that is linked to an external playlist on a media source. 
POST /api/custom-shows/:id/sync
​
id
string (uuid)
required
Custom show UUID.
Response 200 — updated CustomShow object after sync completes. Response 400 — { "error": "Custom show is not configured for sync" } — show has no sync configuration. Response 404 — custom show not found. 
curl -X POST http://localhost:8000/api/custom-shows/c9d8e7f6-0000-0000-0000-000000000002/sync

Build docs developers (and LLMs) love

Get started for freeTalk to us