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.

Channels are the core object in Tunarr. Each channel has a number, a name, a schedule of programs, and a streaming configuration. The Channels API lets you create channels from scratch or by copying an existing one, update every property, retrieve live lineup data, and kick off video streams that any IPTV client can consume.

​
List Channels

Retrieves every channel along with any active streaming sessions. 
GET /api/channels
Response 200 — array of channel objects.
​
id
string (uuid)
Unique identifier for the channel.
​
number
integer
Channel number shown in IPTV clients.
​
name
string
Display name of the channel.
​
groupTitle
string
M3U group-title used for grouping channels in player UIs.
​
startTime
number
Epoch timestamp (ms) of the channel’s schedule epoch origin.
​
duration
number
Total duration in milliseconds of the channel’s current lineup.
​
streamMode
string
Active stream mode: hls, hls_slower, mpegts, hls_direct, or hls_direct_v2.
​
transcodeConfigId
string (uuid)
ID of the transcode configuration attached to this channel.
​
programCount
integer
Total number of programs in the channel’s lineup.
​
sessions
array
Active streaming sessions for this channel (may be empty).
curl http://localhost:8000/api/channels

​
Get Channel

Returns a single channel by its UUID or channel number, including filler collections and active sessions. 
GET /api/channels/:id
​
id
string
required
Channel UUID or channel number.
Response 200 — channel object (same fields as List Channels, plus fillerCollections).
​
fillerCollections
array
Filler lists attached to this channel, each with id, weight, and cooldownSeconds.
Response 404 — channel not found. 
curl http://localhost:8000/api/channels/a1b2c3d4-0000-0000-0000-000000000001

​
Create Channel

Creates a new channel. You may create a brand-new channel (type: "new") or copy an existing one (type: "copy"). 
POST /api/channels
Request body (new channel):
​
type
string
required
Must be "new".
​
channel
object
required
The channel definition. Key fields:
  • name (string, required) — display name
  • number (integer, required) — channel number
  • groupTitle (string) — M3U group title
  • streamMode (string) — hls | hls_slower | mpegts | hls_direct | hls_direct_v2
  • transcodeConfigId (string uuid, required) — transcode configuration to use
  • guideMinimumDuration (number) — minimum EPG slot duration in ms
  • stealth (boolean) — hide channel from EPG
  • offline.mode (string) — offline screen type: "pic" | "clip"
  • watermark (object) — optional watermark/overlay configuration
  • icon (object) — { path, width, duration, position }
Request body (copy channel):
​
type
string
required
Must be "copy".
​
channelId
string (uuid)
required
UUID of the channel to copy.
Response 201 — the newly created channel object. Response 400 — invalid transcode config ID. 
curl -X POST http://localhost:8000/api/channels \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new",
    "channel": {
      "name": "Movies 24/7",
      "number": 42,
      "groupTitle": "Entertainment",
      "streamMode": "hls",
      "transcodeConfigId": "00000000-0000-0000-0000-000000000001",
      "guideMinimumDuration": 300000,
      "stealth": false,
      "offline": { "mode": "pic" },
      "icon": { "path": "", "width": 0, "duration": 0, "position": "bottom-right" }
    }
  }'

​
Update Channel

Replaces all mutable properties of a channel. The channel’s UUID is preserved. 
PUT /api/channels/:id
​
id
string
required
Channel UUID or channel number.
Request body — a SaveableChannel object with the same fields as the channel object in Create Channel. Response 200 — the updated channel object. Response 400 — invalid transcode config ID. Response 404 — channel not found. 
curl -X PUT http://localhost:8000/api/channels/a1b2c3d4-0000-0000-0000-000000000001 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Movies 24/7 HD",
    "number": 42,
    "groupTitle": "Entertainment",
    "streamMode": "hls_direct",
    "transcodeConfigId": "00000000-0000-0000-0000-000000000001",
    "guideMinimumDuration": 300000,
    "stealth": false,
    "offline": { "mode": "pic" },
    "icon": { "path": "", "width": 0, "duration": 0, "position": "bottom-right" }
  }'

​
Delete Channel

Permanently removes a channel and clears it from the EPG and M3U caches. 
DELETE /api/channels/:id
​
id
string
required
Channel UUID or channel number.
Response 200 — channel deleted. Response 404 — channel not found. 
curl -X DELETE http://localhost:8000/api/channels/a1b2c3d4-0000-0000-0000-000000000001

​
Get Channel Lineup

Returns the guide lineup (list of scheduled programs with start/end timestamps) for a channel over an optional time window. If no window is specified the full next schedule block is returned. 
GET /api/channels/:id/lineup
​
id
string
required
Channel UUID or channel number.
​
from
string (ISO 8601 datetime)
Start of the time window (inclusive).
​
to
string (ISO 8601 datetime)
End of the time window (exclusive).
​
includePrograms
boolean
When true, include full program metadata in each lineup entry. Default false.
Response 200 — a ChannelLineup object:
​
id
string (uuid)
Channel UUID.
​
name
string
Channel name.
​
number
integer
Channel number.
​
programs
array
Ordered list of TvGuideProgram entries, each with start, stop, title, duration, and program metadata.
Response 400 — invalid date range. Response 404 — channel not found in guide cache. 
curl "http://localhost:8000/api/channels/a1b2c3d4-0000-0000-0000-000000000001/lineup?from=2024-01-15T18:00:00Z&to=2024-01-15T22:00:00Z"

​
Get All Channel Lineups

Returns the guide lineup for all channels simultaneously, useful for building a full EPG grid client-side. 
GET /api/channels/all/lineups
​
from
string (ISO 8601 datetime)
required
Start of the time window.
​
to
string (ISO 8601 datetime)
required
End of the time window.
​
includePrograms
boolean
Include full program objects in each lineup entry. Default false.
Response 200 — array of ChannelLineup objects (one per channel). Response 400 — invalid date range string.

​
Get Now Playing

Returns the single program currently airing on a channel. 
GET /api/channels/:id/now_playing
​
id
string
required
Channel UUID or channel number.
Response 200 — a TvGuideProgram object for the currently-airing program. Response 404 — channel not found or no guide data available.

​
Get Channel Programs

Returns a paginated list of all programs stored in the channel’s lineup (independent of schedule window). 
GET /api/channels/:id/programs
​
id
string
required
Channel UUID or channel number.
​
offset
integer
Records to skip. Default 0.
​
limit
integer
Maximum records to return.
​
type
string
Filter by content type: movie, episode, track, music_video, other_video.
Response 200 — paginated result { total, size, result: Program[] }.

​
Get Channel Programming (Condensed)

Returns the condensed lineup configuration used internally by the scheduler. This is the representation stored in the database rather than the computed guide. 
GET /api/channels/:id/programming
​
id
string
required
Channel UUID.
​
offset
integer
Pagination offset.
​
limit
integer
Pagination limit (-1 for all).
Response 200 — CondensedChannelProgramming object. Response 404 — channel or lineup not found.

​
Update Channel Programming

Replaces the channel’s lineup with a new set of programs. This is the primary endpoint used by the Tunarr web UI when dragging programs onto a channel. 
POST /api/channels/:id/programming
​
id
string
required
Channel UUID.
Request body — an UpdateChannelProgrammingRequest object specifying the new ordered lineup. Response 200 — the updated CondensedChannelProgramming. Response 404 — channel not found. 
curl -X POST http://localhost:8000/api/channels/a1b2c3d4-0000-0000-0000-000000000001/programming \
  -H "Content-Type: application/json" \
  -d '{ "type": "manual", "programs": [ ... ] }'

​
M3U Playlist

Returns an M3U playlist containing an entry for every channel. This URL is what you add to IPTV clients like Jellyfin Live TV, Plex DVR, Emby Live TV, or VLC. 
GET /api/channels.m3u
​
forceHttps
boolean
Force https:// scheme in stream URLs even when the request came in over HTTP.
​
hostOverride
string
Override the hostname used in stream URLs (useful behind a reverse proxy).
Response 200 — text/plain M3U content. 
curl "http://localhost:8000/api/channels.m3u" -o channels.m3u

​
Stream a Channel

Starts or redirects to the appropriate video stream for a channel. The redirect target depends on the channel’s streamMode:
  • HLS modes → /stream/channels/{uuid}.m3u8
  • MPEG-TS mode → /stream/channels/{uuid}.ts
GET /stream/channels/:id
​
id
string
required
Channel UUID or channel number.
​
streamMode
string
Override the channel’s default stream mode: hls | hls_slower | mpegts | hls_direct | hls_direct_v2.
​
audioOnly
boolean
Request an audio-only stream. Default false.
​
token
string (uuid)
Optional session token (advanced use).
Response — HTTP redirect to the stream URL. 
# Open the stream directly in ffplay
ffplay "http://localhost:8000/stream/channels/42"

​
MPEG-TS Direct Stream

Returns a continuous MPEG-TS video stream for a channel without an intermediate redirect. 
GET /stream/channels/:id.ts
​
id
string
required
Channel UUID or channel number.
​
streamMode
string
Stream mode override.
​
audioOnly
boolean
Audio-only mode. Default false.
Response 200 — binary video/MP2T stream.

​
HLS Playlist

Returns an HLS .m3u8 manifest for a channel. 
GET /stream/channels/:id.m3u8
​
id
string
required
Channel UUID or channel number.
​
mode
string
HLS mode: hls | hls_slower | hls_direct | hls_direct_v2.
Response 200 — HLS manifest (application/vnd.apple.mpegurl).

Build docs developers (and LLMs) love

Get started for freeTalk to us