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 maintains an in-memory Electronic Program Guide (EPG) that tracks what is airing—and what is scheduled to air—on every channel. The Guide API lets you query this data as structured JSON for a specific time window, retrieve the canonical XMLTV file for use with third-party DVR software, and check guide status. IPTV clients like Jellyfin, Plex, Emby, and Channels DVR consume the /api/xmltv.xml endpoint directly.

​
Get Guide for All Channels

Returns the lineup (scheduled programs with start/stop times) for every channel over a specified time range. Results are keyed by channel UUID. 
GET /api/guide/channels
​
dateFrom
string (ISO 8601 or parseable date)
required
Start of the guide window.
​
dateTo
string (ISO 8601 or parseable date)
required
End of the guide window.
Response 200 — Record<string, ChannelLineup> — a map of channel UUID → lineup. Each ChannelLineup contains:
​
id
string (uuid)
Channel UUID.
​
name
string
Channel display name.
​
number
integer
Channel number.
​
icon
object
Channel icon configuration (path, width, duration, position).
​
programs
array
Ordered list of TvGuideProgram entries for the requested window.
Each TvGuideProgram entry contains:
​
start
number
Program start time as an epoch timestamp (milliseconds).
​
stop
number
Program end time as an epoch timestamp (milliseconds).
​
duration
number
Program duration in milliseconds.
​
title
string
Program title.
​
type
string
movie | episode | track | flex | redirect.
​
icon
string
URL or path of the program’s poster/thumbnail art.
Response 400 — invalid or logically impossible date range (e.g. dateFrom after dateTo). 
curl "http://localhost:8000/api/guide/channels?dateFrom=2024-01-15T18:00:00Z&dateTo=2024-01-15T22:00:00Z"

​
Get Guide for a Single Channel

Returns the lineup for one channel identified by UUID or channel number over a specified time range. 
GET /api/guide/channels/:id
​
id
string
required
Channel UUID or channel number.
​
dateFrom
string
required
Start of the guide window (ISO 8601 datetime string or any parseable date).
​
dateTo
string
required
End of the guide window.
Response 200 — ChannelLineup object (same shape as above). Response 404 — "Channel not found in TV guide". Response 500 — internal server error. 
curl "http://localhost:8000/api/guide/channels/42?dateFrom=2024-01-15T20:00:00Z&dateTo=2024-01-15T23:00:00Z"
Example response: 
{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "name": "Movies 24/7",
  "number": 42,
  "icon": {
    "path": "",
    "width": 0,
    "duration": 0,
    "position": "bottom-right"
  },
  "programs": [
    {
      "start": 1705356000000,
      "stop": 1705363200000,
      "duration": 7200000,
      "title": "Jurassic Park",
      "type": "movie",
      "icon": "https://plex.example.com/library/metadata/12345/thumb"
    },
    {
      "start": 1705363200000,
      "stop": 1705365000000,
      "duration": 1800000,
      "title": "Flex",
      "type": "flex"
    }
  ]
}

​
Guide Status

Returns internal diagnostic information about the guide service, including when the guide was last generated and whether it is stale. 
GET /api/guide/status
Response 200 — guide status object (structure may vary by version). Response 500 — server error. 
curl http://localhost:8000/api/guide/status

​
XMLTV Feed

Returns the full XMLTV EPG file for all channels. Configure your DVR software (Jellyfin, Plex, Emby, Channels DVR, etc.) to poll this URL to keep its program guide in sync. 
GET /api/xmltv.xml
The endpoint also supports HEAD requests for cache validation. Tunarr regenerates this file whenever a channel is created, updated, or has its lineup changed, and on a configurable background schedule. Response 200 — application/xml — the XMLTV document. The XMLTV document contains <channel> entries for each channel and <programme> entries covering the schedule window configured in Tunarr’s XMLTV settings (default: 24 hours ahead). 
# Download the XMLTV feed
curl "http://localhost:8000/api/xmltv.xml" -o epg.xml

# Quick peek at the first 40 lines
curl -s "http://localhost:8000/api/xmltv.xml" | head -40
Example XMLTV structure: 
<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="Tunarr">
  <channel id="a1b2c3d4-0000-0000-0000-000000000001">
    <display-name>Movies 24/7</display-name>
    <icon src="http://localhost:8000/images/channels/42.png" />
  </channel>
  <programme
    start="20240115200000 +0000"
    stop="20240115220000 +0000"
    channel="a1b2c3d4-0000-0000-0000-000000000001">
    <title lang="en">Jurassic Park</title>
    <desc lang="en">A theme park suffers a major power breakdown...</desc>
    <category lang="en">movie</category>
    <icon src="https://plex.example.com/library/metadata/12345/thumb" />
  </programme>
</tv>

​
Force XMLTV Refresh

Triggers an immediate regeneration of the XMLTV file outside of the background schedule. 
POST /api/xmltv/refresh
Response 200 — refresh started (synchronous). 
curl -X POST http://localhost:8000/api/xmltv/refresh

​
XMLTV Last Refresh Timestamp

Returns the timestamp of the most recent XMLTV regeneration. 
GET /api/xmltv-last-refresh
Response 200 — { "value": <epoch ms> | undefined }. 
curl http://localhost:8000/api/xmltv-last-refresh

​
Configuring EPG Clients

To connect your DVR software to Tunarr’s guide:
DVR SoftwareM3U URLXMLTV URL
Jellyfinhttp://tunarr-host:8000/api/channels.m3uhttp://tunarr-host:8000/api/xmltv.xml
Plex DVRhttp://tunarr-host:8000/api/channels.m3uhttp://tunarr-host:8000/api/xmltv.xml
Embyhttp://tunarr-host:8000/api/channels.m3uhttp://tunarr-host:8000/api/xmltv.xml
Channels DVRhttp://tunarr-host:8000/api/channels.m3uhttp://tunarr-host:8000/api/xmltv.xml
Replace tunarr-host:8000 with the actual hostname and port where your Tunarr instance is running. If your DVR software is on a different machine from Tunarr, make sure port 8000 is accessible on your network.

Build docs developers (and LLMs) love

Get started for freeTalk to us