Skip to content

API Description

Jump to bottom
dave-p edited this page Jan 20, 2018 · 12 revisions

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 URL must include a username and password with access permissions to carry out the requested task. If TVHeadend has been started with the '--http_root' qualifier, the HTTP root must be included in the URL, thus eg

http://admin:[email protected]: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.

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 or privilege failures will give "401 Unauthorized", 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 to make them easier to read. Functions which perform an action rather than return data will return an empty JSON object on successful completion.

Clone this wiki locally