API - marcelGoerentz/Threadfin GitHub Wiki

Threadfin API

Table of Contents

The Threadfin API is useful for controlling Threadfin outside of the web GUI. It must first be enabled in the Settings page.
It is currently the only way to fetch data on what channels are actively being watched and how many clients are connected to each channel.
Below you will find instructions on how to enable the API and use it from your terminal.

Commands List

The following commands can be used with the Threadfin API:

  • status
  • login
  • getCurrentlyUsedChannels
  • updateM3U
  • updateHDHR
  • updateXMLTV
  • updateXEPG

API (without authentication)

  • Requirement: API must be enabled within the settings page.

Example API Request: Getting the Status (without authentication)

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"status"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"status\"}" http://localhost:34400/api/

API (with authentication)

Requirements:

  • API must be enabled within the settings page.
  • WEB Authentication must be enabled in the settings page.
  • After enabling WEB Authentication, you will need to enable API Authentication below it as well. Refreshing the page after saving may be necessary.
  • The User must have the appropriate rights to perform API requests. Go to the newly created Users page and grant your user account access to the API.

Important:

  • After every API request, a new token is generated.
  • Tokens are valid for 60 minutes and can only be used once.
  • Each API response contains a new token at the bottom of the response, to be used for the next request.

Example API Request: Login and getting the Status (with authentication)

Step 1: Login
Request:
For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"login","username":"ExampleUsername","password":"ExamplePassword"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"login\",\"username\":\"ExampleUsername\",\"password\":\"ExamplePassword\"}" http://localhost:34400/api/

Response:

{
  "token": "U0T-NTSaigh-RlbkqERsHvUpgvaaY2dyRGuwIIvv"
}

Step 2: Getting the Status
Request:
For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"status","token":"U0T-NTSaigh-RlbkqERsHvUpgvaaY2dyRGuwIIvv"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"status\",\"token\":\"U0T-NTSaigh-RlbkqERsHvUpgvaaY2dyRGuwIIvv\"}" http://localhost:34400/api/

Response:

{
  "systemInfo": {
    "appVersion": "1.8.0(29)",
    "apiVersion": "2.0.0",
    "epgSource": "XEPG",
    "systemURLs": {
      "dvr": "localhost:34400",
      "m3u": "http://localhost:34400/m3u/threadfin.m3u",
      "xepg": "http://localhost:34400/xmltv/threadfin.xml"
    },
    "channelInfo": {
      "activeChannels": 185,
      "allChannels": 2049,
      "xepgChannels": 46
    }
  },
  "token": "mXiG1NE1MrTXDtyh7PxRHK5z8iPI_LzxsQmY-LFn"
}

Example Commands

Example Command: getCurrentlyUsedChannels

Use this command to display:

  1. Active playlists.
  2. Channels in the playlist being watched.
  3. The number of active client connections per watched channel.

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"getCurrentlyUsedChannels"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"getCurrentlyUsedChannels\"}" http://localhost:34400/api/

Example Command: updateM3U

Use this command to refresh all M3U playlist data.

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"updateM3U"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"updateM3U\"}" http://localhost:34400/api/

Example Command: updateHDHR

Use this command to refresh all HDHomeRun tuners.

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"updateHDHR"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"updateHDHR\"}" http://localhost:34400/api/

Example Command: updateXMLTV

Use this command to refresh all XMLTV EPG data.

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"updateXMLTV"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"updateXMLTV\"}" http://localhost:34400/api/

Example Command: updateXEPG

Use this command to refresh all XEPG data.

For Unix/Linux/macOS:

curl -X POST -H "Content-Type: application/json" -d '{"cmd":"updateXEPG"}' http://localhost:34400/api/

For Windows:

curl -X POST -H "Content-Type: application/json" -d "{\"cmd\":\"updateXEPG\"}" http://localhost:34400/api/

Notes

  • You can execute these commands from a different computer by replacing localhost with the Threadfin DVR’s IP address. Ensure your network is configured correctly to allow access.
  • For authenticated commands, ensure you use the latest token from the previous API response.
  • All commands except for login are able to be used without WEB Authentication being enabled in the Settings page.
  • The login command will return an empty response unless API Authentication is enabled in the Settings page.
  • If your Threadfin is only available on your local network and you are the only user, setting up authentication and user accounts is not really necessary.