ADMIN privilege is required for all of these functions.

bouquet/class

Lists the text strings, options and defaults used when configuring bouquets within TVH (ie Configuration -> Channel/EPG -> Bouquets).

bouquet/create

Create a new bouquet.

• conf Object describing the new bouquet. An element ext_url is required; presumably in the format of the source element in bouquet/grid.

bouquet/detach

Removes the link from a channel to the bouquet that it is part of.

• uuid uuid(s) of channels to detach.

bouquet/grid

Lists details of bouquets. For details of the parameters and selection criteria which can be applied, see Common Parameters.

{
   "entries" : [
      "uuid": "0d5677d5c370705f3cd3fb53665bc62c",
      "enabled": false,
      "maptoch": false,
      "mapopt": [],
      "chtag": [],
      "chtag_ref": "",
      "name": "Scotland G2: Scotland/BorderSco",
      "ssl_peer_verify": false,
      "ext_url_period": 60,
      "source": "dvb-freesat://dvbs,28.2E,0119,62",
      "services": {},
      "services_seen": 63,
      "services_count": 0,
      "comment": "11428H in Freesat",
      "lcn_off": 0
    }, ...
  ],
  "total": 303
}

bouquet/list

Lists names and bouquets. The list excerpted below is coded into tvheadend.

{
   "entries" : [
      {
         "key" : "e7ddb611669a6a612846415946272f89",
         "val" : "Canal Digitaal SD"
      }, ...
   ]
}

bouquet/scan

Scan (using an available tuner) one or more bouquets to find their channels. The channel list is NOT returned, just an empty JSON object.

• uuid uuid(s) of bouquet(s) to scan.

API calls related to Conditional Access. ADMIN privilege is necessary for all of these functions.

caclient/builders

Lists the text strings, options and defaults used when configuring Conditional Access devices within TVH (ie Configuration -> CAs -> Add).

caclient/class

Lists the text strings, options and defaults used when configuring Conditional Access within TVH (ie Configuration -> CAs).

caclient/create

Create a new CA instance.

• class Name of the class to create, ie one of the classes listed by caclient/builders.

• conf A JSON object describing the new device.

caclient/list

List CA clients.

{
   "entries" : [
      {
         "title" : "Linux DVB CAM (CI/CI+)",
         "status" : "caclientNone",
         "uuid" : "7f435a73b190419cc6e69e3956c50549"
      }
   ]
}

ADMIN privilege is required for all of these functions except config/capabilities.

config/capabilities

Returns a list of some compile-time options which were used to build the software. Requires either 'Web Interface' or 'HTSP Interface' privilege.

[
   "caclient",
   "tvadapters",
   "imagecache",
   "timeshift",
   "trace",
   "libav"
]

config/load

Lists the details, descriptions, defaults and current values of the items in the GUI screen Configuration -> General -> Base. See Common Parameters for details of selection parameters.

config/save

Untested. Updates the server from an object in the format produced by config/load.

• node The JSON object.

memoryinfo/class

Lists the details and descriptions of items in the TVH GUI screen Configuration -> Debugging -> Memory Information Entries.

memoryinfo/grid

Lists details of in-memory objects. See Common Parameters for details of selection parameters.

{
   "entries" : [
      {
         "peak_count" : 17154,
         "name" : "EPG Broadcasts",
         "uuid" : "a1af1bc4f29ba28104e71a540465f250",
         "count" : 17154,
         "peak_size" : 6235792,
         "size" : 6235792
      },
      {
         "peak_count" : 3285,
         "peak_size" : 369303,
         "count" : 3285,
         "size" : 369303,
         "name" : "EPG Series Links",
         "uuid" : "823a78a3bcd05b688c59871455da6399"
      },
      {
         "count" : 11514,
         "peak_size" : 5015593,
         "size" : 5015593,
         "name" : "EPG Episodes",
         "uuid" : "5c666eea1ec3de4bbb9a11f60116b258",
         "peak_count" : 11514
      }, ...
   ],
   "total" : 19
}

pathlist

Lists all of the api functions supported by the server.

[
   "access/entry/class",
   "access/entry/create",
   "access/entry/grid",
   "access/entry/userlist", ...
]

serverinfo

Lists information about the server including the software version number.

{
   "api_version" : 19,
   "webroot" : "/testserver",
   "name" : "Tvheadend",
   "capabilities" : [
      "caclient",
      "tvadapters",
      "trace",
      "libav"
   ],
   "sw_version" : "4.3-943~g9b85e7b7c-dirty"
}

Functions to query and manipulate the list of channels.

A TVH user can only see via the API those channels which have been enabled and to which access has been allowed. However a user with ADMIN privilege can use the parameter all=1 to see details of every channel, channeltag and category even if they do not have access to them.

channel/class

Lists the text strings, options and defaults used when configuring channels within TVH (ie Configuration -> Channel/EPG -> Channel -> Add).

channel/create

Creates a new channel. Requires ADMIN privilege.

• conf A JSON object containing details of the new channel.

channel/grid

Lists details of channels. For details of the parameters and selection criteria which can be applied, see Grid Parameters.

{
   "entries" : [
      {
         "dvr_pst_time" : 0,
         "enabled" : true,
         "epgauto" : true,
         "autoname" : true,
         "name" : "BBC RB 1",
         "number" : 601,
         "tags" : [
            "21d5fe751062c4d99997d6cb48f43c55",
            "1a2a61c4374cedb1fc29417f1a517446"
         ],
         "services" : [
            "9b0e2e103a373350f5e99cda6dd3f055"
         ],
         "epg_running" : -1,
         "epggrab" : [],
         "uuid" : "ae63d3b40fbfab610f49290abc189472",
         "bouquet" : "",
         "dvr_pre_time" : 0
      }, ...
   ],
   "total" : 104
}

channel/list

Lists the names and uuids of all known channels. For disabled channels the channel name is enclosed in braces.

These parameters were added at version 4.3-905:

• numbers If non-zero, the LCN appears before the channel name, separated by a space. Default is zero.

• sources If non-zero, the source appears after the channel name, in square brackets and separated by a space. Default is zero.

• sort Either name to sort by channel name, or numname to sort by LCN then by name (default). The name sort is case-sensitive.

{
   "entries" : [
      {
         "val" : "Channel 5+1",
         "key" : "7e7b77801531c803f5ce8f4d5003f44c"
      }, ...
   ]
}

channel/rename

Renames a channel. Only available from version 4.3.652. Requires ADMIN privilege.

• from The current name of the channel.

• to The new name of the channel.

channeltag/class

Lists the text strings, options and defaults used when configuring channels within TVH (ie Configuration -> Channel/EPG -> Channel Tags -> Add).

channeltag/create

Creates a new channel tag. Requires ADMIN privilege.

• conf A JSON object containing details of the new channel tag.

channeltag/grid

Lists details of channel tags. For details of the parameters and selection criteria which can be applied, see Grid Parameters.

{
   "total" : 5,
   "entries" : [
      {
         "index" : 0,
         "private" : false,
         "icon_public_url" : "",
         "internal" : false,
         "name" : "Radio",
         "titled_icon" : false,
         "enabled" : true,
         "uuid" : "3479ac5a48d6680fc37d8b411cf0e2e8",
         "icon" : "",
         "comment" : ""
      }, ...
   ]
}

channeltag/list

Lists the names and uuids of all channel tags.

{
   "entries" : [
      {
         "key" : "3479ac5a48d6680fc37d8b411cf0e2e8",
         "val" : "Radio"
      }, ...
   ]
}

channelcategory/list

Untested. Return a list of the categories of events which appear in the current EPG and which the user is permitted to see. Used internally to populate the 'Category 1-3' drop-down boxes in DVR -> Autorecs -> Add (Expert view only). The function only works if the EPG is sourced from XMLTV.

TVHeadend provides the API using the HTTP protocol, by default via port 9981 though this can be changed in the TVH config. API functions appear as pseudo-files under the /api/ root of the server filesystem, with parameters passed to the function via either the GET or POST methods.

The call must include a username and password with access permissions to carry out the requested task. The user must also have the ACCESS_WEB_INTERFACE privilege, either directly or inherited from an earlier '*' user. In other words the "Web interface" box must be ticked on the Access Entries screen; without this all calls will fail with a "403 Forbidden" error.

If TVHeadend has been started with the '--http_root' qualifier, the HTTP root must be included in the URL, thus eg

http://admin:admin@192.168.3.45:9981/myHttpRoot/api/serverinfo

The server does not check that all parameters supplied are valid in the context of the request; unexpected items are ignored. Parameters not in the expected format or not containing the expected data may also be ignored.

The response from TVH follows the HTTP protocol and includes an HTTP/1.1 header with status code. If an error occurs the response is in HTML, for example:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<HTML><HEAD>
<TITLE>404 Not Found</TITLE>
</HEAD><BODY>
<H1>404 Not Found</H1>
</BODY></HTML>

The error returned is generic and does not indicate the source of the problem. Authentication failures (incorrect user/pass) will return "401 Unauthorized", lack of privilege "403 Forbidden", non-existent API functions "404 Not Found", incorrect or missing parameters generally "400 Bad Request".

Data is usually returned as JSON, without any CR or LF characters - the examples given have been 'prettified' using json_pp or jq to make them easier to read. Functions which perform an action rather than return data will return an empty JSON object on successful completion.

This section provides information on the HTTP API for TvHeadend. It was written from the source code of the development version 4.3.

The examples shown were mostly generated from UK Freeview DVB-T / DVB-T2 and Freesat DVB-S / DVB-S2, using a single tuner in each case. Other sources and multiple input devices may give different results.

CAUTION

This API is an advanced feature of TVheadend, and the functionality is unstable and liable to change. The software does not completely validate its inputs and incorrect or unexpected calls may result in undesired behaviour.

Functions to list and manipulate access controls. With the exception of access/entry/userlist, ADMIN privilege is required to use these functions.

access/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Access Entries).

access/entry/create

Creates a new user from a JSON object.

• conf The JSON object describing the new user.

access/entry/grid

Lists users and their privileges. See Common Parameters for details of selection parameters.

{
  "entries": [
    {
      "uuid": "59c300295cbf01e53f096242fd5b8ffc",
      "index": 1,
      "enabled": true,
      "username": "*",
      "prefix": "192.168.1.0/24,127.0.0.1/32",
      "change": [
        "change_rights",
        "change_chrange",
        "change_chtags",
        "change_dvr_configs",
        "change_profiles",
        "change_conn_limit",
        "change_lang",
        "change_lang_ui",
        "change_theme",
        "change_uilevel"
      ],
      "uilevel": -1,
      "uilevel_nochange": -1,
      "lang": "eng_GB",
      "langui": "eng_GB",
      "themeui": "blue",
      "streaming": [
        "basic",
        "advanced",
        "htsp"
      ],
      "profile": [],
      "dvr": [
        "basic",
        "htsp",
        "all",
        "all_rw",
        "failed"
      ],
      "htsp_anonymize": false,
      "dvr_config": [
        "4e3a1e13acd2d5a9c129e7b00f6c986e"
      ],
      "webui": true,
      "admin": false,
      "conn_limit_type": 0,
      "conn_limit": 0,
      "channel_min": 0,
      "channel_max": 0,
      "channel_tag_exclude": false,
      "channel_tag": [],
      "comment": "Wildcard",
      "wizard": false
    },
  ]
}

access/entry/userlist

Outputs a list of usernames. The "*" user and any users with a zero-length name are excluded.

The function is used internally to populate the "Owner" dropdown in Digital Video Recorder -> Finished Recordings -> Edit. It MUST be called by a user without ADMIN privileges, otherwise an empty list is returned.

{
   "entries" : [
      {
         "key" : "myUserName",
         "val" : "myUserName"
      }, ...
   ]
}

ipblock/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> IP Blocking Records).

ipblock/entry/create

Creates a new IP-based access record.

• conf The JSON object describing the access record.

ipblock/entry/grid

Lists IP-block records. See Common Parameters for details of selection parameters.

{
   "entries" : [
      {
         "prefix" : "10.0.0.0/8",
         "enabled" : true,
         "comment" : "Don't allow guests",
         "uuid" : "95a81ed085a1d1a9d8647400a878594d"
      }
   ],
   "total" : 1
}

passwd/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Passwords).

passwd/entry/create

Creates a new password record.

• conf The JSON object describing the record.

passwd/entry/grid

Lists passwords for users. Note that "password" is in clear-text while "password2" is base64-encoded with a static prefix. See Common Parameters for details of selection parameters.

{
   "total" : 1,
   "entries" : [
      {
         "password" : "XxXxXxXx",
         "uuid" : "2fa9ebf7e421a537ac032a6905134137",
         "username" : "xxxxxx",
         "enabled" : true,
         "wizard" : true,
         "password2" : "Base64EncodedPassword"
      }, ...
   ]
}

If authentication for the user is by persistent token (requires TVHeadend > 4.3.1500) the entry has some extra fields:

{
   "total" : 1,
   "entries" : [
      {
         "password" : "",
         "uuid" : "2fa9ebf7e421a537ac032a6905134137",
         "username" : "xxxxxx",
         "enabled" : true,
         "wizard" : true,
         "password2" : "Base64EncodedPassword"
         "auth": [
            "enable"
         ],
         "authcode": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
   ]
}

Functions to report on and control Elementary Stream filters.

There are separate API functions to operate on the different types of filter, but they all work in the same way. In the descriptions below the XXX in the function name can be replaced with video, audio, teletext, subtit (subtitle), ca or other as required.

esfilter/XXX/class

Lists the descriptions, options and defaults for configuring the chosen type of filter, ie Configuration -> Stream -> Stream Filters -> {chosen type} -> Add.

esfilter/XXX/grid

Returns the parameters of the defined filters of the chosen type. The usual selection options are available, see

esfilter/XXX/create

Creates a new filter of the chosen type. ADMIN privilege is required.

• conf A JSON object describing the filter.

Manipulate EPG grabbers. ADMIN privilege is required for these functions except for epggrab/channel/list.

epggrab/channel/list

Lists the EPG grabber channels, ie those appearing in Configuration -> Channel / EPG -> EPG Grabber Channels, together with the available option fields and the selections chosen.

epggrab/channel/class

Lists the parameters, descriptions, options and defaults for the GUI screen Configuration -> Channel/EPG -> EPG Grabber Channels.

epggrab/channel/grid

epggrab/module/list

List EPG Grabber Modules, as shown in the GUI screen Configuration -> Channel/EPG -> EPG Grabber Modules.

epggrab/config/load

epggrab/config/save

• node The JSON object.

epggrab/ota/trigger

Queues a run of the OTA EPG grabber.

• trigger Delay in seconds before the run starts. Minimum is one second, maximum is one week.

epggrab/internal/rerun

Run the internal EPG grabbers immediately.

• rerun Not used but must be an integer greater than zero.

ADMIN privilege is required to use these functions except for profile/list.

profile/list

Lists the available stream profiles (visible in the GUI at Configuration -> Stream -> Stream Profiles) together with their uuids.

• all A user with ADMIN privilege can use this parameter to see details of every profile even if the profile is disabled or they do not have access to them.

• htsp If set to 1, list only HTSP profiles. Default is 0 (list all).

{
   "entries" : [
      {
         "val" : "webtv-h264-vorbis-mp4",
         "key" : "1c1f404622fbe9e6133eec69b7c7da6e"
      },
      {
         "val" : "matroska",
         "key" : "03663b00383b34a6ce2a621733388bf5"
      },
      {
         "val" : "webtv-h264-aac-mpegts",
         "key" : "b90da9e0bc0633515b261714a966910d"
      },
      {
         "val" : "webtv-vp8-vorbis-webm",
         "key" : "b171e3a1d2b576e61b8df418e13c5f4a"
      },
      {
         "key" : "8405e0911b97b795d4cd2cddc322dd7f",
         "val" : "webtv-h264-aac-matroska"
      },
      {
         "key" : "b436b4d6bf606fc9954a1fd3dcebe6a8",
         "val" : "audio"
      },
      {
         "val" : "pass",
         "key" : "af143f0b83fd4e919e3fbf05c5561984"
      }
   ]
}

To get the contents of a stream profile use raw/export, passing it the stream profile's uuid.

profile/class

Lists the options, defaults and descriptions of configuration parameters (Configuration -> Stream -> Stream Profiles) in the GUI.

profile/builders

Lists the options, defaults and descriptions of configuration parameters when adding a new stream profile (Configuration -> Stream -> Stream Profiles -> Add) in the GUI.

profile/create

Create a new stream profile.

• class

• conf A JSON object containing details of the new profile.

Functions relating to DVB networks, multiplexes and services. Further service functions can be found in the Service section. ADMIN privilege is required for all these functions.

mpegts/input/network_list

Lists the network(s) associated with a given input device.

• uuid The uuid of the specific hardware device.

To find the input device uuid, use hardware/tree?uuid=root, then take the id value from the output and use it as the value of uuid in another call to hardware/tree. From the output of this function select the id corresponding to the specific front-end device required.

{
   "entries" : [
      {
         "key" : "c70bb0e55db15cf44c72a8acb49d5ed7",
         "val" : "Sandy"
      }
   ]
}

mpegts/network/grid

Lists available networks. The standard parameters listed in Grid Parameters may be used. The items returned depend on the type of network - terrestrial, satellite, IPTV etc.

curl http://192.168.1.1:9981/api/mpegts/network/grid |jq 
{
  "entries": [
    {
      "uuid": "546f654e5e9abe67386f9ea3516987a3",
      "url": "file:///home/hts/iptvlist.m3u8",
      "channel_number": 0,
      "refetch_period": 60,
      "ssl_peer_verify": false,
      "tsid_zero": false,
      "remove_args": "",
      "ignore_path": 0,
      "scan_create": false,
      "service_sid": 1,
      "priority": 0,
      "spriority": 0,
      "max_streams": 0,
      "max_bandwidth": 0,
      "max_timeout": 15,
      "remove_scrambled": true,
      "enabled": true,
      "networkname": "iptv",
      "pnetworkname": "iptvlist",
      "nid": 0,
      "autodiscovery": 0,
      "bouquet": false,
      "skipinitscan": true,
      "idlescan": false,
      "sid_chnum": false,
      "ignore_chnum": false,
      "charset": "AUTO",
      "localtime": 0,
      "num_mux": 100,
      "num_svc": 100,
      "num_chn": 0,
      "scanq_length": 0,
      "wizard": false
    },
    {
      "uuid": "c9a4516fa61feef914de797a799f11d2",
      "orbital_pos": "28.2E",
      "enabled": true,
      "networkname": "Freesat",
      "pnetworkname": "ASTRA",
      "nid": 0,
      "autodiscovery": 2,
      "bouquet": false,
      "skipinitscan": false,
      "idlescan": false,
      "sid_chnum": false,
      "ignore_chnum": false,
      "charset": "AUTO",
      "localtime": 0,
      "num_mux": 79,
      "num_svc": 602,
      "num_chn": 193,
      "scanq_length": 0,
      "wizard": true
    }
  ],
  "total": 2
}

mpegts/network/class

Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Networks).

mpegts/network/builders

Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Network -> Add).

mpegts/network/create

Create a new network.

• class Required. The class name matching the class item obtained from a call to mpegts/network/builders.

• conf Required. A JSON object containing the settings for this network.

mpegts/network/mux_class

Lists the text strings, options and defaults used when editing a multiplex using Configuration -> DVB Inputs -> Muxes -> Edit.

• uuid The value of network_uuid from a call to mpegts/mux/grid.

mpegts/network/mux_create

Create a mux for an existing network.

• uuid The uuid of the network containing this mux.

• conf A JSON object containing the settings for this mux. The contents will depend on the type of network.

A JSON object containing the UUID of the new mux is returned.

curl -d uuid=62d279b29fff2de0ff1245dad5154500 -d 'conf={"enabled":1,"epg":0,"epg_module_id":"","delsys":"DVBS","frequency":12440000,"symbolrate":29500000,"polarisation":"V","modulation":"QPSK","fec":"8/9","scan_state":0,"charset":"","rolloff":"AUTO","pilot":"AUTO","dvb_satip_dvbc_freq":0,"dvb_satip_dvbt_freq":0,"tsid_zero":false,"pmt_06_ac3":0,"eit_tsid_nocheck":false,"sid_filter":0,"stream_id":-1,"pls_mode":"ROOT","pls_code":1}'
 "http://192.168.0.1:9981/api/mpegts/network/mux_create"

mpegts/network/scan

Triggers a scan of the requested network(s).

• uuid uuid(s) of the network(s) to scan. More than one may be given; they will be scanned in sequence.

mpegts/mux/grid

Lists available multiplexes. The standard parameters listed in Grid Parameters may be used.

• hidemode If set to all, only enabled multiplexes are listed. The default is to show all multiplexes.

{
   "total" : 9,
   "entries" : [
      {
         "created" : 1508497835,
         "delsys" : "DVB-T",
         "scan_state" : 0,
         "tsid" : 24640,
         "scan_first" : 1508761027,
         "name" : "690MHz",
         "pnetwork_name" : "Cambs & Beds",
         "transmission_mode" : "8k",
         "sid_filter" : 0,
         "network_uuid" : "c70bb0e55db15cf44c72a8acb49d5ed7",
         "onid" : 9018,
         "num_svc" : 35,
         "eit_tsid_nocheck" : false,
         "num_chn" : 29,
         "hierarchy" : "NONE",
         "tsid_zero" : false,
         "pmt_06_ac3" : 0,
         "network" : "Sandy",
         "scan_last" : 1509267382,
         "bandwidth" : "8MHz",
         "fec_lo" : "NONE",
         "frequency" : 690000000,
         "constellation" : "QAM/64",
         "fec_hi" : "3/4",
         "epg" : 1,
         "guard_interval" : "1/32",
         "scan_result" : 1,
         "enabled" : 1,
         "uuid" : "0245c791efc3fa448c19db2f000d0d8f",
         "plp_id" : -1
      }, ...
   ]
}

mpegts/mux/class

Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Muxes).

mpegts/service/grid

Lists available mpegts services. The standard parameters listed in Grid Parameters may be used.

• hidemode The default is to show only services where the multiplex is enabled and the service has been verified. Setting this parameter to all also hides services which are not enabled, setting it to none shows all services.

curl http://192.168.1.1:9981/api/mpegts/service/grid | jq
{
   "entries" : [
      {
         "uuid": "105984f18272f0e05107b296a1ea9d2a",
         "network": "Freesat",
         "multiplex": "11914.5H",
         "multiplex_uuid": "bb4aaf3f77880e60bdfc6fd33fc4efc1",
         "sid": 5229,
         "lcn": 0,
         "lcn_minor": 0,
         "lcn2": 0,
         "srcid": 0,
         "svcname": "Sky Arts",
         "provider": "BSkyB",
         "dvb_servicetype": 1,
         "dvb_ignore_eit": false,
         "prefcapid": 0,
         "prefcapid_lock": 0,
         "force_caid": 0,
         "pts_shift": 0,
         "created": 1623526273,
         "last_seen": 1662095234,
         "enabled": true,
         "auto": 0,
         "channel": [
            "4e3dacb42fa6aff571ff2ce2d143d70d"
         ],
         "priority": 0,
         "encrypted": false,
         "caid": "",
         "s_type_user": -1
      }, ...
   ]
  "total": 908
}

dvb_servicetype can be used to determine what kind of service is being broadcast. The possibilities are:

• Radio: 0x02

• SD TV: 0x01, 0x16, 0x17, 0x18, 0x80, 0x96, 0xa8, 0xd3

• HD TV: 0x11, 0x19 - 0x1e, 0x91, 0xa0, 0xa4, 0xa6

• UHDTV: 0x1f

mpegts/service/class

Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Services).

mpegts/mux_sched/class

Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Mux Schedulers).

mpegts/mux_sched/grid

List the entries as found under Configuration -> DVB Inputs -> Mux Schedulers. The standard parameters listed in Grid Parameters may be used.

{
   "entries" : [
      {
         "mux" : "93b544d663e5313b12991fe9926ae4af",
         "restart" : false,
         "enabled" : true,
         "uuid" : "feab6167cd0596388382441987f33678",
         "timeout" : 600,
         "cron" : "30 3 * * *"
      }
   ],
   "total" : 1
}

mpegts/mux_sched/create

Untested. Create a mux schedule, presumably from a structure similar to that from mpegts/mux_sched/grid.

dvb/orbitalpos/list

Lists orbital positions and the satellites occupying them. The list is distributed with tvheadend; satellite reception is not necessary to use this API.

{
   "entries" : [
      {
         "key" : "177W",
         "val" : "177W : NSS 9"
      }, ...
   ]
}

dvb/scanfile/list

Lists the available frequency scan tables.

• type One of 'dvb-s', 'dvb-t', 'dvb-c', 'atsc-t', 'atsc-c', 'isdb-t'.

• satpos For dvb-s, the satellite position in degrees multiplied by 10 with East positive (so 28.2E is written as 282). The position must be accurate within +/- 0.2 degrees.

This function requires the dvb-scan files to be present on the server. They are installed by default (in /usr/share/tvheadend/data/) but are omitted if configure argument '--disable-dvbscan' is used. Distributions may also choose to package them separately.

{
   "entries" : [
      {
         "val" : "> 28.2E:Astra",
         "key" : "dvb-s/geo/dvb-s_> 28.2E:Astra"
      }
   ]
}

ADMIN privilege is required for all of these functions except codec_profile/list.

codec/list

Lists available codecs and their properties. This is a very verbose list.

codec_profile/class

Lists the text strings, options and defaults used when configuring codec profiles.

codec_profile/create

Add a new codec profile.

• class The name of the codec profile.

• conf A JSON object describing the codec profile.

codec_profile/list

{
   "entries" : [
      {
         "uuid" : "d3f76d002a895f5c65dd57715d169399",
         "title" : "webtv-vorbis (WEBTV codec Vorbis)",
         "status" : "codecEnabled"
      },
      {
         "status" : "codecEnabled",
         "title" : "webtv-aac (WEBTV codec AAC)",
         "uuid" : "77e7184d6ade386137f553de0687254d"
      },
      {
         "title" : "webtv-h264 (WEBTV codec H264)",
         "status" : "codecEnabled",
         "uuid" : "eb7281ade724c77d23add9223bc2a480"
      }
   ]
}

Functions to query the Electronic Program(me) Guide.

epg/events/grid

Query the EPG and optionally apply filters.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

• mode If set to the string now then only events currently playing are listed.

• title A (case-insensitive) string which must appear in the title to be listed.

• fulltext If set to 1 then the title string must match exactly. Default is 0.

• channel The channel to show events from, specified either by channel name or uuid. Must be an exact match to the data from channel/list, otherwise all channels are returned.

• channelTag The (single) channel tag to show events from, specified either by name or uuid. Must be an exact match to the data from channeltag/list, otherwise all tags are returned.

• durationMin Shortest event to be listed (seconds).

• durationMax Longest event to be listed (seconds).

• contentType Integer representing the genre to be listed - see epg/content_type/list.

• filter A JSON object describing the filter(s) to be applied. See Grid Filters for the syntax. String filters can only be applied to the 'channelName', 'title', 'subtitle', 'summary', 'description' and 'extraText' fields.

• sort The key to be sorted by. Default is to sort by 'start'.

• dir If sort is specified, setting 'dir' to 'desc' reverses the sort order

• start First record to be listed from the database, default is 0.

• limit Number of records to list. Default is 50 - use a very large number to get all.

• new If set to 1 then only events marked as 'new' will be included. Default is 0. The EPG source must identify 'new' events for this filter to work.

• cat1, cat2, cat3 XMLTV provides more details of the event category than the OTA EPG, and these parameters can be used to filter by XMLTV category. See Channel-Category.

EPG sources differ in the information which they provide, and there are many more information items possible than are included in the example below. Any items which have no data available will be omitted.

{
   "totalCount" : 18575,
   "entries" : [
      {
         "serieslinkUri" : "crid://www.channel4.com/M4EI0021031162146302",
         "serieslinkId" : 510179,
         "episodeId" : 510180,
         "episodeUri" : "crid://www.channel4.com/41408/013",
         "summary" : "Tony Robinson and the Team descend on the bleak landscape of Bodmin Moor to examine a Bronze Age village and a vast, ancient 300m-long stone structure.  [S]",
         "genre" : [
            160
         ],
         "channelName" : "More 4",
         "title" : "Time Team",
         "start" : 1508760600,
         "subtitled" : 1,
         "channelUuid" : "e1b1de65605dc4e13bac6d4478e66a44",
         "eventId" : 510178,
         "nextEventId" : 510181,
         "widescreen" : 1,
         "stop" : 1508764500,
         "subtitle" : "Tony Robinson and the Team descend on the bleak landscape of Bodmin Moor to examine a Bronze Age village and a vast, ancient 300m-long stone structure.  [S]",
         "channelNumber" : "14",
         "ageRating" : 9,
         "ratingLabel" : "PG,
         "ratingLabelIcon" : "imagecache/37"
      }, ...
   ]
}

If the event is scheduled to be recorded, these extra items will appear:

      "dvrUuid": "f01433995f76d60f3b32d38fb18f541a",
      "dvrState": "scheduled",

Other possible values for dvrState are "recording", "completed", "completedError", "completedWarning" and "completedRerecord". The 'completed' values can only be present if the recording stopped before the scheduled stop time.

epg/events/alternative

Lists alternative broadcasts of the same event.

• eventId Identifier of the event, eg taken from epg/events/grid.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

The function looks for broadcasts having the same eventId, rather than using event CRIDs. It does not work on UK DVB-T.

This function does not work on TVH versions older than 4.2.4-5 or 4.3-589.

epg/events/related

Lists broadcasts related to the given event.

• eventId Identifier of the event, eg taken from epg/events/grid.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

The function looks for events having the same series link ID as the given event, ie part of the same series of broadcasts. It therefore relies on the EPG provider filling in these details.

Note that the series link ID is unique to an individual set of broadcasts; if the series is repeated on a different channel (or at a different time) the series link will be different.

This function does not work on TVH versions older than 4.2.4-5 or 4.3-589.

From version 4.3.1711, if the given event does not have a series link ID, events in the EPG having the same title are returned.

epg/events/load

Lists details of specific event(s).

• eventId Identifier of the event, or a JSON array of event Ids.

The common parameters which apply to other 'load' functions do not work here.

{
   "entries" : [
      {
         "serieslinkId" : 261067,
         "channelUuid" : "e61af00ea8b71683b9a1f41515fa83d3",
         "title" : "Take Me Out",
         "nextEventId" : 262992,
         "widescreen" : 1,
         "summary" : "Paddy McGuinness presents the dating show. The likely lads include a chocolate factory worker, a city slicker, an oil rig engineer and a gymnast. [S]",
         "channelNumber" : "113",
         "channelName" : "ITV2+1",
         "serieslinkUri" : "crid://www.itv.com/ebs44033",
         "genre" : [
            48
         ],
         "subtitle" : "Paddy McGuinness presents the dating show. The likely lads include a chocolate factory worker, a city slicker, an oil rig engineer and a gymnast. [S]",
         "episodeId" : 262718,
         "episodeUri" : "crid://www.itv.com/1616462450",
         "eventId" : 262991,
         "start" : 1515005400,
         "stop" : 1515009600,
         "subtitled" : 1,
         "ageRating" : 9,
         "ratingLabel" : "PG,
         "ratingLabelIcon" : "imagecache/37"
      }
   ],
   "totalCount" : 1
}

epg/brand/list

A 'Brand' is a commonly-available show, eg "Simpsons". What constitutes a 'Brand' is up to the EPG provider.

This function was removed in version 4.3.1059.

epg/content_type/list

Lists the Content Type IDs extracted from ETSI EN 300 468 together with their descriptions. The Content Type ID appears in the output of epg/events/grid as "Genre". IDs described as 'Reserved' or 'User Defined' in the specification are given the description of the previous ID instead.

• full If set to 0 (the default) only the broad categories defined by content_nibble_level_1 in the specification are listed. If set to 1 all categories are listed.

{
   "entries" : [
      {
         "val" : "",
         "key" : 0
      },
      {
         "val" : "Movie / Drama",
         "key" : 16
      },
      {
         "key" : 17,
         "val" : "Detective / Thriller"
      }, ...
   ]
}

ADMIN privilege is required to use these functions.

satips/config/load

Lists the descriptions, options, defaults and current settings for configuring the SAT>IP server capability - see Configuration -> General -> SAT>IP server.

satips/config/save

Untested. Updates the server from an object in the format produced by satips/config/load.

• node The JSON structure containing the updates.

Functions to query and manipulate the list of parental rating labels ('G', 'M', 'PG', etc).

ratinglabel/class

Lists the text strings, options and defaults used when configuring parental rating labels within TVH (ie Configuration -> Channel/EPG -> Rating Labels -> Add).

ratinglabel/create

Creates a new parental rating label. Requires ADMIN privilege.

• conf A JSON object containing details of the new parental rating label.

ratinglabel/grid

Lists details of parental rating labels. For details of the parameters and selection criteria which can be applied, see Grid Parameters.

{
   "entries" : [
      {
         "uuid : "a82438515ecc857dbf2509517ff3fe40",
         "enabled" : true,
         "country" : "AUS",
         "age" : 8,
         "display_age" : 11,
         "display_label" : "PG",
         "label" : "PG",
         "authority" : "ACMA",
         "icon" : "file:///my/file/location/acma-pg.png",
         "icon_public_url" : "imagecache/37"
      }, ...
   ],
   "total" : 9
}

ratinglabel/list

Lists the names and uuids of all known parental rating labels.

{
   "entries" : [
      {
         "val" : "AUS",
         "key" : "7b1f8773747155ed7341c8328a037f28"
      }, ...
   ]
}

Notes:

• Parental rating labels were added to Tvheadend in December 2023.

• Processing of parental rating labels is disabled by default and can be enabled via Configuration -> Channel/EPG -> EPG Grabber.

• Tvheadend will automatically create a placeholder record as new labels are encountered.

• Parental rating label fields will not appear in other modules, (DVR, EPG) if the processing of parental rating labels is disabled.

These function provide direct access to the internal data structures of TVHeadend. Attempting to modify these internal structures may have unwanted effects including loss of data.

Information is held within TVHeadend in a key-value database. The key for each record is a random 128-bit value called a uuid. The value is a data structure which can be represented in JSON format. The record is called an idnode.

The content of each idnode depends on what it represents; this is indicated by the value of the class parameter.

Although no special privilege is required to call these functions, access control is applied to the data items being referenced.

idnode/load

Read the value of one or more idnode records. One (and only one) of these parameters must be specified:

• uuid The uuid (or JSON-structured list of uuids) to read.

• class The class of records to read, ie one of the classes returned by classes.

If uuid is given, the data to be returned may be qualified by setting one of these parameters to an integer greater than zero:

• meta Include meta-data (default values and descriptions of the data items).

• grid Return a brief summary of the records.

If class is given, setting the parameter enum to an integer value greater than zero returns only a set of key-value pairs.

In both cases the list parameter can be used to select which items are to be output, based on the value of the 'id' field. Multiple entries can be selected, separated by commas, colons or semicolons. A '-' in front of an entry deselects that item (and implicitly selects all others).

idnode/save

Update an existing idnode.

• node The JSON object (or array of objects) containing the update.

Each update must contain the uuid item. Other items supplied replace those in the idnode; they are not merged.

Fields within an idnode may be read-only; for this reason it may not be possible to take the data from idnode/load and use it as input to idnode/save (thanks to Poul Kalff for this information). To check the read-only status of a field, use idnode/class and check for a 'rdonly' flag.

idnode/tree

Read information held in a tree structure (eg for tuner devices).

• uuid The uuid of the starting point in the tree structure, or the special value 'root'.

• root The uuid of the head of the tree structure. Required if uuid = 'root'.

idnode/class

List information about a specified class; mostly metadata used to configure the TVHeadend UI.

• name The name of the class, ie one of the values returned by classes.

idnode/delete

Delete one or more records.

• uuid The uuid (or a JSON-formatted list) of the record(s) to be deleted.

idnode/moveup

idnode/movedown

This section includes functions to manipulate recorder objects; timers, autorecs and recordings. Unless noted otherwise, RECORDER privilege is required for all these functions - the 'Basic' tick-box in the 'Video Recorder' drop-down on the Access Entry screen. Other tick-boxes will be needed for some functions.

dvr/config/class

Lists the text strings, options and defaults used when configuring the DVR capability within TVH (ie Configuration -> Recording). Requires either RECORDER or ADMIN privilege.

dvr/config/grid

Lists the configuration sets available for the TVH server together with their options. Configurations are identified by their name parameter; the default config has the name blank. Requires either RECORDER or ADMIN privilege.

{
   "total" : 1,
   "entries" : [
      {
         "cache" : 2,
         "storage-mfree" : 1000,
         "autorec-maxsched" : 0,
         "whitespace-in-title" : false,
         "time-in-title" : false,
         "channel-dir" : false,
         "epg-running" : true,
         "name" : "",
         "episode-in-title" : false,
         "profile" : "af143f0983fd4e91953fb859c5561984",
         "clean-title" : false,
         "pre-extra-time" : 0,
         "uuid" : "4e3a1e1cacd2d559c129e7b90f6c986e",
         "day-dir" : false,
         "subtitle-in-title" : false,
         "epg-update-window" : 86400,
         "title-dir" : false,
         "warm-time" : 30,
         "windows-compatible-filenames" : false,
         "autorec-maxcount" : 0,
         "removal-days" : 2147483647,
         "storage-mused" : 0,
         "tag-files" : true,
         "clone" : true,
         "omit-title" : false,
         "enabled" : true,
         "storage" : "/mnt/tvheadend",
         "date-in-title" : false,
         "channel-in-title" : false,
         "post-extra-time" : 0,
         "skip-commercials" : false,
         "rerecord-errors" : 0,
         "file-permissions" : "0664",
         "retention-days" : 2147483646,
         "charset" : "ASCII",
         "pri" : 2,
         "directory-permissions" : "0775",
         "pathname" : "$t$n.$x"
      }
   ]
}

dvr/config/create

Creates a new configuration set. Requires ADMIN privilege.

• name configuration name. Must be supplied and cannot be blank

• conf parameter set, passed as a JSON object

dvr/entry/class

Lists the text strings, options and defaults used when editing an upcoming recording.

dvr/entry/grid

Lists all of the recordings that TVH knows about, ie it combines the output of grid_upcoming, grid_finished, grid_failed and grid_removed. Use the status parameter to tell them apart.

See Grid Parameters for parameter details, and note the default is to return only the first 50 items.

dvr/entry/grid_upcoming

Lists all of the currently-scheduled recordings. See Grid Parameters for parameter details, and note the default is to return only the first 50 items.

• duplicates Set to 0 to exclude duplicate timers. Default is 1.

The data is derived from the EPG when the timer was scheduled. From version 4.3.1013 the item "disp_extratext" is included to deal with the inconsistent use of "subtitle" and "summary" fields by broadcasters.

The values of start_real and stop_real take into account the recorder padding and warm-up time currently set.

The value of rating_label_uuid points to a current parental rating label record.

{
  "entries": [
    {
      "uuid": "bc85208b236701a63568cb62d5506e08",
      "enabled": true,
      "create": 1561451356,
      "watched": 0,
      "start": 1562099400,
      "start_extra": 0,
      "start_real": 1562099340,
      "stop": 1562103000,
      "stop_extra": 0,
      "stop_real": 1562103000,
      "duration": 3600,
      "channel": "9a20ebf5ec10a3c49c2c021cc2698ecc",
      "channelname": "BBC TWO HD",
      "image": "",
      "fanart_image": "",
      "title": {
        "eng": "Inside the Bank of England"
      },
      "disp_title": "Inside the Bank of England",
      "disp_subtitle": "",
      "summary": {
        "eng": "1/2. Filmed with unprecedented access, this episode goes inside the Bank to show how it prints our cash, ensures our money holds its value and sets the UKs interest rate. [S,AD] [HD]"
      },
      "disp_summary": "1/2. Filmed with unprecedented access, this episode goes inside the Bank to show how it prints our cash, ensures our money holds its value and sets the UKs interest rate. [S,AD] [HD]",
      "description": {
        "eng": "1/2. Filmed with unprecedented access, this episode goes inside the Bank to show how it prints our cash, ensures our money holds its value and sets the UKs interest rate. [S,AD] [HD]"
      },
      "disp_description": "1/2. Filmed with unprecedented access, this episode goes inside the Bank to show how it prints our cash, ensures our money holds its value and sets the UKs interest rate. [S,AD] [HD]",
      "disp_extratext": "1/2. Filmed with unprecedented access, this episode goes inside the Bank to show how it prints our cash, ensures our money holds its value and sets the UKs interest rate. [S,AD] [HD]",
      "pri": 6,
      "retention": 0,
      "removal": 0,
      "playposition": 0,
      "playcount": 0,
      "config_name": "4e3a1e13acd2d5a9c129e7b00f6c986e",
      "owner": "tvheadend",
      "creator": "tvheadend",
      "filename": "",
      "errorcode": 0,
      "errors": 0,
      "data_errors": 0,
      "dvb_eid": 3842,
      "noresched": false,
      "norerecord": false,
      "fileremoved": 0,
      "uri": "crid://fp.bbc.co.uk/m/4586",
      "autorec": "24fcfd056fc32b86f0abd9fc6a57d17d",
      "autorec_caption": "Inside the Bank of England (Inside the Bank of England - Created from EPG query)",
      "timerec": "",
      "timerec_caption": "",
      "parent": "",
      "child": "",
      "content_type": 2,
      "copyright_year": 0,
      "broadcast": 295634,
      "episode_disp": "",
      "url": "",
      "filesize": 0,
      "status": "Scheduled for recording",
      "sched_status": "scheduled",
      "duplicate": 0,
      "first_aired": 0,
      "comment": "Auto recording: Inside the Bank of England - Created from EPG query",
      "category": [],
      "credits": {},
      "keyword": [],
      "genre": [
        32
      ],
      "age_rating": 11,
      "rating_label_saved": "PG,
      "rating_icon_saved": "file:///my/file/location/acma-pg.png",
      "rating_country_saved": "AUS",
      "rating_authority_saved": "ACMA",
      "rating_label_uuid": "a82438515ecc857dbf2509517ff3fe40",
      "rating_icon": "imagecache/37",
      "rating_label": "PG"
    }, ...
  ],
  "total": 4
}

dvr/entry/grid_finished

Lists recordings which have completed and which are still in the TVH logs. See Grid Parameters for parameter details, and note the default is to return only the first 50 items.

The values of start_real and stop_real take into account the recorder padding and warm-up time currently set - not the values which were set when the recording was made. If this is a segmented recording (a programme split into two or more parts with for example a news bulletin in between) the value of stop_real is the end time of the final segment, while stop is the end time of he first segment.

Because legislation can change over time, the value of rating_label_uuid is blank for finished DVR entries, the 'saved' tags should be used instead.

{
  "entries": [
    {
      "uuid": "07ac8ed6d7d8744a4217c7b7005d5d7a",
      "enabled": true,
      "create": 1581300276,
      "watched": 0,
      "start": 1581937200,
      "start_extra": 0,
      "start_real": 1581937110,
      "stop": 1581940800,
      "stop_extra": 0,
      "stop_real": 1581940800,
      "duration": 3600,
      "channel": "16460c1b17ee679e0fc3cdb851edd294",
      "channel_icon": "imagecache/223",
      "channelname": "YESTERDAY",
      "image": "",
      "fanart_image": "",
      "title": {
        "eng": "Abandoned Engineering"
      },
      "disp_title": "Abandoned Engineering",
      "disp_subtitle": "",
      "disp_summary": "",
      "description": {
        "eng": "Pyramiden Norway: A town with a supernatural atmosphere, a collection of imposing buildings in southern Australia, and the remains of curious-looking basins emerging from the waves. [AD,S]"
      },
      "disp_description": "Pyramiden Norway: A town with a supernatural atmosphere, a collection of imposing buildings in southern Australia, and the remains of curious-looking basins emerging from the waves. [AD,S]",
      "disp_extratext": "Pyramiden Norway: A town with a supernatural atmosphere, a collection of imposing buildings in southern Australia, and the remains of curious-looking basins emerging from the waves. [AD,S]",
      "pri": 6,
      "retention": 0,
      "removal": 0,
      "playposition": 0,
      "playcount": 0,
      "config_name": "1ccca1a328ecdcab3f88640dda5b6209",
      "owner": "linvdr",
      "creator": "linvdr",
      "filename": "/video/tvheadend/Abandoned Engineering-4.ts",
      "errorcode": 0,
      "errors": 0,
      "data_errors": 0,
      "dvb_eid": 0,
      "noresched": true,
      "norerecord": false,
      "fileremoved": 0,
      "uri": "crid://onid-2/QQK596",
      "autorec": "",
      "autorec_caption": "",
      "timerec": "",
      "timerec_caption": "",
      "parent": "",
      "child": "",
      "content_type": 2,
      "copyright_year": 0,
      "broadcast": 0,
      "episode_disp": "",
      "url": "dvrfile/07ac8ed6d7d8744a4217c7b7005d5d7a",
      "filesize": 997310108,
      "status": "Completed OK",
      "sched_status": "completed",
      "duplicate": 0,
      "first_aired": 0,
      "comment": "Auto recording: New: Abandoned Engineering - Created from EPG query",
      "category": [],
      "credits": {},
      "keyword": [],
      "genre": [],
      "age_rating": 13,
      "rating_label_saved": "M",
      "rating_icon_saved": "file:///my/file/location/acma-m.png",
      "rating_country_saved": "AUS",
      "rating_authority_saved": "ACMA",
      "rating_label_uuid": "",
      "rating_icon": "imagecache/35",
      "rating_label": "M"
    }, ...
  "total": 101
}

dvr/entry/grid_failed

Lists failed recordings. See Grid Parameters for parameter details.

If you merge the 'failed' and 'completed' recordings into a single list, the only way to tell which list the entries originally came from is by using the status field.

   "total" : 1,
   "entries" : [
      {
         "parent" : "",
         "channelname" : "BBC Four HD",
         "start" : 1513112400,
         "stop_real" : 1513116000,
         "description" : {
            "eng" : "2/3. Series in which Sam Willis reveals stories of invasion in Britain, including the Barbary Corsaire pirates and the tale of King Louis the Lion, who invaded in the 13th century. [HD] [S]"
         },
         "comment" : "Auto recording: Created from EPG query",
         "disp_title" : "New: Invasion! with Sam Willis",
         "child" : "",
         "uri" : "crid://fp.bbc.co.uk/247LP4",
         "image" : "",
         "dvb_eid" : 62795,
         "autorec_caption" : " (Created from EPG query)",
         "removal" : 0,
         "url" : "dvrfile/22d9847b550b8fe9e39e01bda2e41777",
         "owner" : "tvheadend",
         "copyright_year" : 0,
         "playposition" : 0,
         "filename" : "/video/tvheadend/New: Invasion! with Sam Willis.ts",
         "start_real" : 1513112355,
         "start_extra" : 0,
         "duration" : 3600,
         "category" : [],
         "creator" : "tvheadend",
         "playcount" : 0,
         "sched_status" : "completed",
         "status" : "Too many data errors",
         "autorec" : "5cf012bf5c78e23d3c89c59c172414cb",
         "errors" : 0,
         "norerecord" : false,
         "broadcast" : 0,
         "noresched" : true,
         "keyword" : [],
         "config_name" : "ffb7136480e16dac47c8e71bd7686537",
         "disp_subtitle" : "2/3. Series in which Sam Willis reveals stories of invasion in Britain, including the Barbary Corsaire pirates and the tale of King Louis the Lion, who invaded in the 13th century. [HD] [S]",
         "enabled" : true,
         "stop_extra" : 0,
         "pri" : 6,
         "retention" : 0,
         "subtitle" : {
            "eng" : "2/3. Series in which Sam Willis reveals stories of invasion in Britain, including the Barbary Corsaire pirates and the tale of King Louis the Lion, who invaded in the 13th century. [HD] [S]"
         },
         "disp_description" : "2/3. Series in which Sam Willis reveals stories of invasion in Britain, including the Barbary Corsaire pirates and the tale of King Louis the Lion, who invaded in the 13th century. [HD] [S]",
         "fileremoved" : 0,
         "filesize" : 2171129092,
         "credits" : {},
         "title" : {
            "eng" : "New: Invasion! with Sam Willis"
         },
         "content_type" : 2,
         "genre" : [],
         "errorcode" : 0,
         "stop" : 1513116000,
         "channel_icon" : "",
         "data_errors" : 510410,
         "timerec" : "",
         "channel" : "7bd448424af369b19f22511b1ece023c",
         "uuid" : "22d9847b550b8fe9e39e01bda2e41777",
         "timerec_caption" : "",
         "first_aired" : 0,
         "duplicate" : 0
      }
   ]
}

dvr/entry/grid_removed

Lists removed recordings. See Grid Parameters for parameter details.

Under some circumstances an unsuccessful recording may appear here rather than under failed recordings. For example when EIT-based accurate recording is being used and the 'running' status is never received.

If TVH is configured to delete the log record when a recording is deleted this function will not return them.

dvr/entry/create

Creates a new timer from a JSON object.

• conf The JSON object describing the timer. Items not specified are derived from the default profile of the user. An example of the minimum useful JSON is shown below.

{
   "start":1509397200,
   "stop":1509400800,
   "channelname":"Channel 5",
   "title":{
      "eng":"Paddington Station 24/7"
   },
   "subtitle":{"eng":"More real-life dramas..."}
}

The function returns the uuid of the created timer on success.

It is also possible using this function to add a file created elsewhere into the TVH database as a completed recording. Items needed in the JSON are:

{
    "enabled": true,
    "start": 1509000000,
    "stop":  1509003600,
    "channelname": "local file",
    "title": {
        "eng": "my title"
    },
    "subtitle": {
        "eng": "filename: my video"
    },
    "description": {
        "eng": "my description"
    },
    "comment": "added by tvh_addfile.py",
    "files": [
        {
            "filename": "/full/path/to/videofile.ts"
        }
    ]
}

It is important that the start and stop times are in the past, otherwise TVH will try to create a timer to record the event. (Thanks to "ullix tv" for this information.) Also note that the ability to add a pre-recorded file is unintended behaviour - see Caution.

dvr/entry/create_by_event

Creates a new timer using details from the EPG. Input parameters are:

• config_uuid this is the uuid parameter from the output of dvr/config/grid

• event_id this is the eventId parameter for the event, taken from epg/events/grid

dvr/entry/rerecord/toggle, dvr/entry/rerecord/deny, dvr/entry/rerecord/allow

These functions provide the same capability as the Re-record button in Digital Video Recorder -> Finished Recordings. "Allow" sets the recording to be re-done, "deny" cancels a scheduled rerecording, "toggle" reverses the rerecord state.

• uuid the uuid of the finished or failed recording, or a JSON object containing an array of uuids.

dvr/entry/stop

Gracefully stops a running recording.

• uuid The uuid value from the timer's entry in dvr/entry/grid.

dvr/entry/cancel

Deletes a timer or aborts a running recording.

• uuid The uuid value from the timer's entry in dvr/entry/grid.

If the timer is running, the recording is kept on disk but classified as a 'failed' recording.

NOTE To delete a series use idnode/delete, passing parameter uuid from the entry in dvr/timerec/grid. As with the UI, deleting a series deletes all pending timers for that series.

dvr/entry/prevrec/toggle, dvr/entry/prevrec/set, dvr/entry/prevrec/unset

These three functions affect the "previously recorded" status of a timer. If set, either directly or via a call to the toggle function, the timer is marked as completed and the file flagged as deleted. If unset, a new timer is created.

These functions provide the same capability as the Previously Recorded button in Digital Video Recorder -> Upcoming/Current Recordings. It can be used to 'hide' re-runs to prevent them being re-recorded.

dvr/entry/remove

Removes a completed recording from storage.

• uuid The recording's uuid value from dvr/entry/grid_finished.

dvr/entry/filemoved

Informs TVH that a recording has been relocated (by external means) within the filesystem. Requires ADMIN privilege.

• src The original full path to the file

• dst The new full path to the file

dvr/entry/move/finished

Move a finished recording entry to the "Finished Recordings" category, presumably from "Failed Recordings". The actual file is not moved.

• uuid The uuid of the entry, or an array of entries passed as a JSON object.

dvr/entry/move/failed

Move a finished recording entry to the "Failed Recordings" category, presumably from "Finished Recordings". The actual file is not moved.

• uuid The uuid of the entry, or an array of entries passed as a JSON object.

dvr/autorec/class

Lists the text strings, options and defaults used when creating or editing a series timer.

dvr/autorec/grid

Lists autorecs (series timers). See Grid Parameters for parameter details.

{
   "entries" : [
      {
         "record" : 0,
         "pri" : 6,
         "channel" : "a931256950c3f8aa5c5416cd36175e13",
         "content_type" : 0,
         "retention" : 0,
         "fulltext" : false,
         "start_window" : "Any",
         "serieslink" : "crid://www.five.tv/R5HP0",
         "config_name" : "4e3a1e13acd2d5a9c129e7b00f6c986e",
         "maxduration" : 0,
         "removal" : 0,
         "start_extra" : 0,
         "stop_extra" : 0,
         "maxcount" : 0,
         "owner" : "tvheadend",
         "weekdays" : [
            1,
            2,
            3,
            4,
            5,
            6,
            7
         ],
         "uuid" : "f2c30b9757e66567bf2d8ec6de60314c",
         "creator" : "tvheadend",
         "tag" : "",
         "maxsched" : 0,
         "comment" : "Created from EPG query",
         "start" : "Any",
         "btype" : 0,
         "brand" : "",
         "enabled" : true,
         "season" : "",
         "minduration" : 0,
         "title" : "New: Paddington Station 24/7"
      }, ...
   ],
   "total" : 9
}

dvr/autorec/create

Create a new series timer by specifying search parameters. To create a timer using CRIDs use dvr/autorec/create_by_series.

• conf A JSON object specifying the selection parameters for the timer.

• config_uuid The uuid parameter from the output of dvr/config/grid. Parameter config_name may be passed instead.

dvr/autorec/create_by_series

Creates a new series timer using CRIDs. Input parameters are:

• config_uuid The uuid parameter from the output of dvr/config/grid

• event_id The eventId parameter for one event in the series, taken from epg/events/grid

NOTE To delete a series use idnode/delete, passing parameter uuid from the entry in dvr/autorec/grid. As with the UI, deleting a series deletes all pending timers for that series.

dvr/timerec/class

Lists the text strings, options and defaults used when creating or editing a time-based recording.

dvr/timerec/grid

Lists time-based recordings. See Grid Parameters for parameter details.

{
   "total" : 1,
   "entries" : [
      {
         "name" : "My Timerec",
         "title" : "Time-%F_%R",
         "enabled" : true,
         "channel" : "7bd448424af369b19f22511b1ece023c",
         "retention" : 0,
         "config_name" : "ffb7136480e16dac47c8e71bd7686537",
         "creator" : "tvheadend",
         "uuid" : "458251fe1963a9967e5b83e8f2a680e6",
         "weekdays" : [
            2,
            4
         ],
         "pri" : 6,
         "owner" : "tvheadend",
         "stop" : "19:30",
         "start" : "19:00",
         "removal" : 0
      }
   ]
}

dvr/timerec/create

Create a new time-based timer.

• conf A JSON object specifying the selection parameters for the timer.

A JSON object is returned containing the UUID of the timerec.

language/list

Produces a list of all known languages and their three-letter ISO639-3 codes. The list is hard-coded within the Tvheadend source.

{
   "entries" : [
      {
         "val" : "Undetermined",
         "key" : "und"
      },
      {
         "key" : "aar",
         "val" : "Afar"
      },
      {
         "val" : "Abkhazian",
         "key" : "abk"
      }, ...
   ]
}

language/locale

Produces a similar list to language/list but also including the full RFC3066 locale reference for those locales which have been compiled into Tvheadend.

{
  "entries" : [
  ...
    {
      "key": "elx",
      "val": "Elamite"
    },
    {
      "key": "eng",
      "val": "English"
    },
    {
      "key": "eng_US",
      "val": "English (US)"
    },
    {
      "key": "eng_GB",
      "val": "English (GB)"
    },
    {
      "key": "epo",
      "val": "Esperanto"
    }, ...
  ]
}

language/ui_locale

Produces a list in the same format as language/locale but containing only those locales which are supported by TVHeadend (ie have translations available).

Grid parameters

API calls which end in /grid, with the exception of epg/events/grid, have a common set of parameters:

• start First entry to include. Default is the first (0).

• limit Number of entries to include. Default is 50 - use a large number to get all.

• filter A JSON object describing the filter(s) to be applied. See Grid Filters below for syntax.

• sort Name of the field to sort the records by. A case-sensitive sort is used.

• dir if sort is specified then dir=desc produces a reverse sort.

Grid filters

A filter can be applied to the output using a JSON object. The syntax is:

filter=[
            {
                "field" : "<fieldname>",
                "type"  : "string|numeric|boolean",
                "value" : "<value>",
                "comparison" : "gt|lt|eq",
                "intsplit" : <intsplit>
             }, ...
        ]

The "comparison" field is only used with numeric data. A "gt" comparison actually matches on greater-or-equal, and "lt" on less-or-equal.

Boolean values must be specified as "0" or "1" (NOT "true" or "false"). A (case-insensitive) regular expression match is used for strings.

The "intsplit" field is used for integer variables which are used to store a quotient and remainder, and defines how the bits of the variable are allocated.

Multiple filters can be applied to a query ONLY if they refer to different fields, so for example it is not possible to query for EPG events having start times between two values.

Load parameters

API calls which end in /load, with the exception of epg/events/load, have a common set of parameters:

• meta If > 0 an extra data structure is output, mostly related to the format of the GUI screen where the information is presented. Default is 0.

• list This parameter selects which items in the params array are to be output, based on the value of the 'id' field. Multiple entries can be selected, separated by commas, colons or semicolons. A '-' in front of an entry deselects that item (and implicitly selects all others).

List details of input devices. ADMIN privilege is required for these functions.

hardware/tree

Lists the parameters, options and settings for input devices.

• uuid (Required). If set to 'root', the top-level details of the input device(s) are shown. If the uuid of a device (obtained from the top-level details) is submitted, full information is shown similar to Configuration -> DVB Inputs -> TV Adaptors.

• root Function obscure.

[
   {
      "leaf" : 0,
      "uuid" : "efe25f71ce456f99bb5a1b600b2e8143",
      "class" : "linuxdvb_adapter",
      "params" : [
         {
            "nosave" : true,
            "caption" : "Active",
            "id" : "active",
            "default" : false,
            "rdonly" : true,
            "noui" : true,
            "value" : true,
            "type" : "bool"
         },
         {
            "caption" : "Device path",
            "type" : "str",
            "id" : "rootpath",
            "rdonly" : true,
            "default" : "",
            "value" : "/dev/dvb/adapter0",
            "description" : "Path used by the device."
         }
      ],
      "text" : "/dev/dvb/adapter0 [Montage Technology M88DS3103 #0]",
      "caption" : "LinuxDVB adapter",
      "id" : "efe25f71ce456f99bb5a1b600b2e8143",
      "event" : "linuxdvb_adapter"
   }
]

hardware/satip/discover

Triggers a discovery process for SAT>IP servers, as Configuration -> General -> SAT>IP Server -> Discover SAT>IP Servers in the GUI. This function is only available if SAT>IP client functionality has been compiled into TVHeadend.

ADMIN privilege is required for these functions.

timeshift/config/load

Lists the descriptions, options and defaults for configuring the timeshift capability - see Configuration -> Recording -> timeshift.

timeshift/config/save

Untested. Set the timeshift configuration.

• node Unknown.

Lists the available character sets.

Although no special privilege is needed to use these functions, access control is applied at the inode database level.

classes

Returns a list of all data classes together with readable titles. Requires version 4.3-406 or later.

raw/export

• class One of the class names returned by .

• uuid A single uuid or JSON array of uuids.

Returns data about the selected object(s). The information is the same as returned by the corresponding grid function (where available) but without the selection and filtering options provided by that function.

raw/import

• node A JSON object or array of objects.

Objects being imported must have a uuid and must already exist in the database.

Lists statistics of input sources and connections. ADMIN privilege is required for all these functions.

status/connections

Lists currently-connected client devices.

status/subscriptions

Lists currently-active subscriptions.

status/inputs

Lists statistics of input devices.

For DVB-T and DVB-S tuners at least, the signal and SNR values are only non-zero while TVH is actively using the device. Some items may be missing if the device is idle.

The meaning of the statistics is below. Not all input sources provide all of the values.

For signal_scale and snr_scale, a value of 1 indicates that the corresponding signal or SNR reading is relative; 65535 = 100%. A value of 2 indicates the reading is absolute; 1000 = 1dB. A value of 0 indicates that the reading is not available or not valid.

The "pids" data is only present in TVH versions 4.3.1420 and later.

status/inputclrstats

Resets the input counters to zero.

connections/cancel

Disconnects one or more clients.

These examples (and any other use of the API which passes username and password in the URL) will only work if TVheadend is configured to use 'basic' or 'basic and digest' authentication.

curl

Parameters passed to TVH using the GET method must be URI-encoded:

curl 'http://user:pass@localhost:9981/api/epg/events/grid?limit=999&channel=BBC%20ONE'

Alternatively use the POST Method:

curl --data 'limit=999&channel=BBC ONE' 'http://user:pass@localhost:9981/api/epg/events/grid'

To make the output more human-readable, pipe it through json_pp (included in the perl package on many distributions) or jq.

PHP

This simple example lists some details about upcoming timers, sorted in date order. To work through a PHP-enabled web server, the PHP.INI setting "allow_url_fopen" must be ON.

For an example of what can be done with the API in PHP see https://github.com/dave-p/TVHadmin.

Javascript

It is a 'feature' of Javascript that a script can only access remote content from the same source (IP and port number) as the script was loaded from. Hence to call the TVHeadend API from Javascript, the script must be hosted on TVHeadend's built-in web server. To do this, place your script in /usr/share/tvheadend/src/webui/static; it can then be accessed from URL http://user:pass@your.server:9981/static/. Note that this is unintended behaviour and may change in the future.

This example carries out the same task as the PHP example above. Your browser will prompt for the TVHeadend user and password.

Python

This example produces the same output as the previous ones.

ADMIN privilege is required for these functions.

tvhlog/config/load

Lists the details, descriptions, defaults and current values of the items in the GUI screen Configuration -> Debugging -> Configuration -> Settings. See for details of selection parameters.

tvhlog/config/save

Untested. Updates the server from an object in the format produced by .

• node The JSON object.

tvhlog/subsystem/grid

List the subsystems available for trace and debug operations.

Also see and .

• id - The internal enum for this subsystem. These values may change between systems depending upon the application version and the options used at compile-time but are otherwise constant.

• subsystem - The name of the subsystem. These values are to be used in the WebUI when enabling trace/debug operations.

• description - The locale-aware description of the subsystem.

• trace - True if this subsystem is currently being traced.

• debug - True if this subsystem is currently being debugged.

• traceCount - The number of subsystems with trace currently set to true.

• debugCount - The number of subsystems with debug currently set to true.

• totalCount - The total number of subsystems.

Note 1: Users may enter a special all subsystem (not listed) instead of nominating each subsystem individually in the WebUI. This condition can be detected if traceCoount and/or debugCount is equal to totalCount.

Note 2: As at April 2014, the id field is informational only. It is provided to facilitate future API development.

ADMIN privilege is required to use all of these functions.

service/mapper/load

Lists the descriptions, options, current values and defaults of the GUI screen Configuration -> DVB Inputs -> Services. -> Map Services.

Further API functions for manipulating DVB services are in the section.

service/mapper/save

Untested. Set the Service Mapper options.

• node Unknown, possibly the value of class.

service/mapper/stop

Stops a running service mapper operation.

service/mapper/status

Provides the same output as Status -> Service Mapper in the TVH GUI.

service/list

Lists available services. "Available" services includes those which are disabled or encrypted.

• enum If set to 1 (as an integer without quotes) a short-form list is output containing each service's uuid and name. If set to 0 (the default) a verbose list is generated.

• list If enum is not 1 this parameter selects which items in the params array are to be output, based on the value of the 'id' field. Multiple ids can be selected, separated by commas, colons or semicolons. A '-' in front of an id deselects that item (and implicitly selects all others).

raw/export?class=service provides a simpler version of the same information (but including the streams data), however the API call is about 50% slower.

service/streams

Lists the streams comprising the service.

• uuid uuid of the service. This parameter is mandatory; it is not possible to list all services.

service/removeunseen

Remove services which have not been seen recently. This call carries out the same action as Configuration -> DVB Inputs -> Services -> Maintenance in the TVH GUI.

• days The number of unseen days before deletion. The default is 7 days, the minimum is 5 days.

• type If set to pat the action is the same as "Remove unseen services (PAT/SDT)" in the GUI. Otherwise the action is the same as "Remove all unseen services".

An empty JSON object is always returned.

Tvheadend has a WebSocket interface on port 9981. It is used by the UI to provide 'live' actions and updates, avoiding the need to refresh the screen.

Example Code

The example below creates a WebSocket connection to the Tvheadend server and listens for updates.

<!DOCTYPE html>
<html lang="">
  <head>
    <meta charset="utf-8">
    <title>Websocket Test</title>
    <script>
      let socket = new WebSocket("ws://192.168.0.1:9981/comet/ws");
      socket.onmessage = function(event) {
        let message = event.data;
        let messageElem = document.createElement('div');
        messageElem.textContent = message;
        document.getElementById('messages').prepend(messageElem);
      }
    </script>
  </head>
  <body>
    <header></header>
    <main>
      <div id="messages"></div>
    </main>
    <footer></footer>
  </body>
</html>

Output

Tvheadend transmits messages on the Websocket interface asynchronously, when either an event occurs or in some cases at scheduled intervals. The output format is JSON.

Each message contains a key "messages" whose value is an array of message objects. Each message object contains a key "notificationClass" which specifies the source of the message, and a series of message-specific key-value pairs.

{
  "messages": [
    {
      "freediskspace": 607828439040,
      "useddiskspace": 135628398200,
      "totaldiskspace": 861450428416,
      "notificationClass": "diskspaceUpdate"
    },
    {
      "notificationClass": "logmessage",
      "logtxt": "2024-03-06 11:06:14.444 subscription: 00D5: \"HTTP\" subscribing on channel \"DMAX\", weight: 100, adapter: \"DVB-T #0\", network: \"Sandy\", mux: \"690MHz\", service: \"DMAX\", profile=\"pass\", hostname=\"192.168.1.2\", client=\"VLC/3.0.20 LibVLC/3.0.20\""
    },
    {
      "id": 213,
      "start": 1709723174,
      "errors": 0,
      "state": "Running",
      "hostname": "192.168.1.2",
      "client": "VLC/3.0.20 LibVLC/3.0.20",
      "title": "HTTP",
      "channel": "DMAX",
      "service": "DVB-T #0/Sandy/690MHz/DMAX",
      "pids": [
        1011,
        2401,
        2402,
        2403,
        2404
      ],
      "profile": "pass",
      "in": 57716,
      "out": 57716,
      "total_in": 57716,
      "total_out": 57716,
      "updateEntry": 1,
      "notificationClass": "subscriptions"
    }
  ]
}

This section describes other functions which can be accessed via HTTP. They are not part of the HTTP API and so are not preceded by 'api'.

Unless otherwise stated no special privilege is needed to use these functions.

comet/poll

Returns a JSON object containing data used by the Tvheadend UI, including the disk space utilisation.

The "freediskspace" and "totaldiskspace" figures relate to the disk partition holding the recorder Storage Path, "useddiskspace" is the total size of all files stored below that point. These figures may not give the actual storage situation if there are multiple storage devices and mount points.

curl  "http://192.168.0.1:9981/comet/poll" | jq

{
  "boxid": "1cee949b52c05872fdb24c8bc2dccc0a41fdb33b",
  "messages": [
    {
      "notificationClass": "accessUpdate",
      "uilevel": "expert",
      "theme": "blue",
      "quicktips": 1,
      "chname_num": 0,
      "chname_src": 0,
      "date_mask": "",
      "label_formatting": 0,
      "username": "",
      "address": "192.168.0.1",
      "dvr": 1,
      "admin": 1,
      "time": 1709799071,
      "cookie_expires": 2047,
      "ticket_expires": 300,
      "info_area": "login,storage,time",
      "freediskspace": 608234205184,
      "useddiskspace": 135222628776,
      "totaldiskspace": 861450428416
    },
    {
      "notificationClass": "setServerIpPort",
      "ip": "192.168.0.1",
      "port": 9981
    }
  ]
}

See WebSocket for a WebSocket interface to this function.

dvrfile

Downloads a previously-recorded file. Called with the UUID of the recording. Requires appropriate privilege (DVR or streaming).

http://192.168.0.1:9981/dvrfile/968ecf2073e4ec2e45c0ad534acdd4bf

epgsave

Flushes the contents of the EPG to disk.

eventinfo

Used by simple.html.

favicon.ico

Downloads an icon file. The filename is hard-coded in the source; on installation it is usually placed at /usr/share/tvheadend/src/webui/static/img/logo.png.

imagecache

Outputs an image from the image cache. Requires streaming, recording or web interface privilege.

$ curl  http://192.168.0.1:9981/imagecache/<image-number>

markdown

Used to download help files.

ping

Available on version 4.3-2124 and later. Provides a simple way to check that the server is alive. No authentication is needed to use this function.

curl http://192.168.0.1:9981/ping
PONG

play

This function acts as a front-end to the dvrfile and stream functions. It is invoked using the following forms:

http://192.168.0.1:9981/play/stream/channelnumber/<channelnumber>
http://192.168.0.1:9981/play/stream/mux/cc23a085f4ff2cb41a8f58ad85570fde
http://192.168.0.1:9981/play/dvrfile/968ecf2073e4ec2e45c0ad534acdd4bf

The function examines the 'User-Agent' string sent by the client. If the user-agent is on a preset list (or is not present), data transfer starts immediately; if not then a playlist is returned to the client.

The User-Agent list is "MPlayer", "curl/", "wget/", "TVHeadend", "Lavf" and any string containing "shoutcastsource".

If ticket is added to the URL, for example:

http://192.168.0.1:9981/play/ticket/stream/channelnumber/<channelnumber>

the url in the returned playlist will contain an authentication ticket, removing any need to enter credentials in order to access the data. However the ticket is only valid for five minutes so the playlist cannot be re-used after that time.

When playing streams, the parameters for the underlying stream function can also be used.

playlist

This is a complex function which outputs lists of content available from the server, in various formats and filtered in several ways. The syntax for invoking the function depends on the required output and not all combinations of inputs are valid.

Note: The hostname portion of the URLs returned within the resulting playlist, for example m3u, will be the same as the hostname supplied with the http request.

List all tags

$ curl http://192.168.0.1:9981/playlist/tags

See below for sample output.

List all channels or recordings

$ curl http://192.168.0.1:9981/playlist/y/x/channels
$ curl http://192.168.0.1:9981/playlist/y/recordings

The value of <x> in the URL specifies the format of the output. The options are e2, m3u or satip, with m3u the default if the item is omitted. For recordings only m3u is available.

For channels, a parameter sort can be added. This can take the value 'name' or 'numname', to sort the output by channel name or channel number respectively.

See below for notes including the values of <y> in the URL, and sample outputs.

List filtered channels or recordings

$ curl http://192.168.0.1:9981/playlist/y/x/channelid/<channelid>
$ curl http://192.168.0.1:9981/playlist/y/x/channelnumber/<channelnumber>
$ curl http://192.168.0.1:9981/playlist/y/x/channelname/<channelname>
$ curl http://192.168.0.1:9981/playlist/y/x/channel/<channelUUID>
$ curl http://192.168.0.1:9981/playlist/y/x/tagid/<tagid>
$ curl http://192.168.0.1:9981/playlist/y/x/tagname/<tagname>
$ curl http://192.168.0.1:9981/playlist/y/x/tag/<tagUUID>

$ curl http://192.168.0.1:9981/playlist/y/dvrid/<dvr_id>

The value of <x> in the URL specifies the format of the output. The options are e2, m3u or satip, with m3u the default if the item is omitted. For recordings only m3u is available.

See below for notes including the values of <y> in the URL, and sample outputs.

Notes

The list of recordings includes all entries in the DVR logs, including failed and missed recordings and recordings to be made in the future (ie timers). Unplayable recordings have 'bandwidth=0' in the output.

The value of <y> in the URLs, if supplied, specifies whether the channel list or playlist should include authentication in the URL. If <y> is ticket, each entry includes an access-control 'ticket' - these tickets are only valid for five minutes, they are different for each channel/recording listed, and calling the playlist again will output a different set of tickets.

Alternatively, if Persistent Authentication is in use (TVHeadend versions > 4.3.1485), the value of <y> may be set to auth. The auth code must be appended to the URL as a parameter, eg.

$ curl http://192.168.0.1:9981/playlist/auth/tags?auth=8ef7aa08e516060ca4330730c60e00d5b5174920

Sample outputs

$ curl  http://192.168.0.1:9981/playlist/tags
#EXTM3U
#EXTINF:-1 logo="",HDTV
http://192.168.0.1:9981/playlist/tagid/1267929608?profile=pass
#EXTINF:-1 logo="",Radio channels
http://192.168.0.1:9981/playlist/tagid/1970563711?profile=pass
...

$ curl  http://192.168.0.1:9981/playlist/channels
#EXTINF:-1 tvg-id="90a325df8d683eb014cf0abf56943e8d" tvg-chno="1005",CNN
http://192.168.0.1:9981/stream/channelid/1596302224?profile=pass
#EXTINF:-1 tvg-id="c44d3390a7b5ecb59a074fff73a6b532" tvg-chno="2000",BBC R4 FM
http://192.168.0.1:9981/stream/channelid/271797700?profile=pass
...

$ curl  http://user:pass@192.168.0.1:9981/playlist/ticket/channels
#EXTINF:-1 tvg-id="4d422960b4d45e8e007eaa8b3bf58190" tvg-chno="69",QUEST+1
http://192.168.0.1:9981/stream/channelid/1613316685?ticket=5609a7022c1a7b5f8ac8b22aff2638a3efd78cdc&profile=pass
#EXTINF:-1 tvg-id="85f9c040b03cd5496a2d950b2380d793" tvg-chno="70",Quest Red+1
http://192.168.0.1:9981/stream/channelid/1086388613?ticket=d89df723230fa791e11b1e17cc1962e55fe73230&profile=pass
...

$ curl  http://192.168.0.1:9981/playlist/e2/channelname/QUEST
#NAME QUEST
#SERVICE 1:0:0:0:0:0:0:0:0:0:http://192.168.1.1:9981/stream/channelid/344789476&profile=pass:QUEST
#DESCRIPTION QUEST

$ curl  http://192.168.0.1:9981/playlist/satip/channelname/QUEST
#EXTINF:-1,QUEST
http://192.168.1.1:9981/stream/channelid/344789476?profile=pass

$ curl  http://192.168.1.0:9981/playlist/recordings
#EXTM3U
#EXTINF:1800,The Repair Shop
#EXT-X-TARGETDURATION:1800
#EXT-X-STREAM-INF:PROGRAM-ID=da01a7de69dfd8d09241c045d6fbaeb6,BANDWIDTH=5115
#EXT-X-PROGRAM-DATE-TIME:2018-03-23T18:30:00+0000
http://192.168.0.1:9981/dvrfile/da01a7de69dfd8d09241c045d6fbaeb6
#EXTINF:1800,The Hitchhiker's Guide to the...
#EXT-X-TARGETDURATION:1800
#EXT-X-STREAM-INF:PROGRAM-ID=74cb4b64f55afca54725d8ab0a3d3e00,BANDWIDTH=0
#EXT-X-PROGRAM-DATE-TIME:2018-04-05T18:30:00+0100
http://192.168.0.1:9981/dvrfile/74cb4b64f55afca54725d8ab0a3d3e00

pvrinfo

Used by simple.html.

redir

Used internally for theme selection?

satip_server

Outputs one of two files describing the SAT>IP server and the services available from it.

$ curl  http://192.168.0.1:9981/satip_server/desc.xml
$ curl  http://192.168.0.1:9981/satip_server/satip.m3u

simple.html

A rudimentary user interface to TVHeadend. It shows the contents of the recorder log (both completed and future recordings) and allows entries to be cancelled or deleted. A search box allows the EPG to be scanned for matching entries; clicking on an entry opens an information page which contains a button allowing the event to be recorded. Requires RECORDER privilege.

special/srvid2

Outputs details of encrypted services. Each item contains:

• Service ID

• CA ID

• CA provider ID

• Service name

• Service type

• Service provider name

2968:0B00|TRP 1|TV||ASTRA
177B:0963,0961,0960|Crime+Inv+1|TV||ASTRA
0E1F:0963,0961,0960|Virgin Two|TV||ASTRA
13FB:0963,0961,0960|VICE|TV||ASTRA
2584:0963,0961,0960|Virgin One+1|TV||ASTRA
1789:0963,0961,0960|Real Lives+1|TV||ASTRA
15AE:0963,0961,0960|History+1|TV||ASTRA
15AF:0963,0961,0960|History2|TV||ASTRA
15AD:0963,0961,0960|History|TV||ASTRA
15B3:0963,0961,0960|Nat Geo Wild|TV||ASTRA
15B1:0963,0961,0960|Nat Geo+1|TV||ASTRA
15B0:0963,0961,0960|Nat Geo|TV||ASTRA

state

Outputs the TVHeadend version number and a (text) list of channels. This function requires Admin privilege.

The binary hash is only filled-in if the server runs on an x86 processor.

$ curl  'http://user:pass@192.168.0.1:9981/state'

Tvheadend 4.3-1215~g5782d8c14-dirty  Binary SHA1: 0000000000000000000000000000000000000000

Channels
----------------------------------------------
tru TV (13183175)
  refcount = 0
  number = 156
  icon = <none set>

ITV3 (54665543)
  refcount = 0
  number = 114
  icon = <none set>
...

status.xml

Outputs the current status of the server, including CPU load average, recordings in progress (or minutes to the next recording) and the number of active subscriptions. Needs 'Web interface' or 'Recorder' privilege.

<?xml version="1.0"?>
 <currentload>
  <systemload>0.000000,0.000000,0.000000</systemload>
  <recordings>
   <recording>
    <next>465</next>
   </recording>
  </recordings>
  <subscriptions>0</subscriptions>
 </currentload>

<?xml version="1.0"?>
<currentload>
 <systemload>0.390000,0.090000,0.030000</systemload>
 <recordings>
  <recording>
   <start>
    <date>2020/05/24</date>
    <time>09:00</time>
    <unixtime>1590307200</unixtime>
    <extra_start>60</extra_start>
   </start>
   <stop>
    <date>2020/05/24</date>
    <time>13:00</time>
    <unixtime>1590321600</unixtime>
    <extra_stop>300</extra_stop>
   </stop>
   <title>Soft Rock Classics! 1980-1989</title>
   <status>Recording</status>
  </recording>
 </recordings>
 <subscriptions>1</subscriptions>
</currentload>

stream

Starts the streaming of live data from a channel, service or mux. The parameters which can be applied depend on the source:

 http://192.168.0.1:9981/stream/channelid/<chid>
 http://192.168.0.1:9981/stream/channel/<uuid>
 http://192.168.0.1:9981/stream/channelnumber/<channelnumber>
 http://192.168.0.1:9981/stream/channelname/<channelname>

• profile. The streaming profile to use. If the specified profile does not exist or can not be used the 'htsp' profile is used if available.

• qsize. Streaming buffer size. Default is 1500000 bytes.

• User-Agent. Use unknown.

 http://192.168.0.1:9981/stream/service/<uuid>

• profile. The streaming profile to use. If the specified profile does not exist or can not be used the 'htsp' profile is used if available.

• qsize. Streaming buffer size. Default is 1500000 bytes.

• descramble. If set to 0 Tvheadend does not descramble the service.

• emm. Unknown. Default is 0, set to 1 to activate.

• User-Agent. Use unknown.

 http://192.168.0.1:9981/stream/mux/<muxid>

• qsize. Streaming buffer size. Default is 10000000 bytes.

• pids. A comma-separated list of pids to stream, or the word 'all' to stream the raw mux. The default is to stream all.

udpstream

Controls the streaming of live data from a channel or service to a UDP address and port. This function requires Tvheadend version 4.3.2038 or later.

The following parameters are mandatory:

• address. The IP address of the device to receive the UDP stream.

• port. The destination port address.

The remaining parameters for the start function depend on the source:

 http://192.168.0.1:9981/udpstream/<start|stop>/channelid/<chid>
 http://192.168.0.1:9981/udpstream/<start|stop>/channel/<uuid>
 http://192.168.0.1:9981/udpstream/<start|stop>/channelnumber/<channelnumber>
 http://192.168.0.1:9981/udpstream/<start|stop>/channelname/<channelname>

• profile. The streaming profile to use. If the specified profile does not exist or can not be used a 'Not Allowed' error is output.

• qsize. Streaming buffer size. Default is 1500000 bytes.

• User-Agent. Use unknown.

 http://192.168.0.1:9981/udpstream/<start|stop>/service/<uuid>

• profile. The streaming profile to use. If the specified profile does not exist or can not be used a 'Not Allowed' error is output.

• qsize. Streaming buffer size. Default is 1500000 bytes.

• descramble. If set to 0 Tvheadend does not descramble the service.

• emm. Default is 0, set to 1 to activate.

• User-Agent. Use unknown.

xmltv

Outputs the EPG in XML format, filtered in various ways.

$ curl http://192.168.0.1:9981/xmltv/channelid/<channelid>
$ curl http://192.168.0.1:9981/xmltv/channelnumber/<channelnumber>
$ curl http://192.168.0.1:9981/xmltv/channelname/<channelname>
$ curl http://192.168.0.1:9981/xmltv/channel/<channelUUID>
$ curl http://192.168.0.1:9981/xmltv/tagid/<tagid>
$ curl http://192.168.0.1:9981/xmltv/tagname/<tagname>
$ curl http://192.168.0.1:9981/xmltv/tag/<tagUUID>

The final variation lists the complete EPG together with a channel list. Example:

$ curl  http://192.168.0.1:9981/xmltv/channels

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="TVHeadend-4.3-1670~ge37c696de-dirty" source-info-name="tvh-Tvheadend">
<channel id="7e7b77801531c803f5ce8f4d5003f44c">
  <display-name>Channel 5+1</display-name>
</channel>
...
<programme start="20181231151500 +0000" stop="20181231161500 +0000" channel="7e7b77801531c803f5ce8f4d5003f44c">
  <title lang="eng">Dirty Dancing</title>
  <desc lang="eng">Classic starring Patrick Swayze and Jennifer Grey. A spoiled 17-year-old learns a lot about life from the hotel dance instructor during a family summer holiday. (1987)[S]</desc>
  <category lang="en">Movie / Drama</category>
</programme>
...
</tv>

If Persistent Authentication is in use (TVHeadend versions > 4.3.1485), the auth code must be appended to the URL as a parameter.