1 of 25

API Description

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.

Common Parameters

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).

Access

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

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.

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

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

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