TapHome API

Using TapHome API it is possible to integrate TapHome devices into any 3rd party application. For example Apple Siri voice control.

If you are interested in direct communication with Control unit within LAN or VPN, please consider using

Integration Protocol (AMX, Lutron, Crestron, Control4, Clipsal)

Overview

TapHome API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why TapHome API can be used practically for any programming language.

TapHome TapHome API overview:

You access the resource by sending an HTTP request to the TapHome TapHome API server. The server replies with a response that contains the data you requested
All resources are located at https://api.taphome.com/api/TapHomeApi/v1/
All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request)
You request a particular resource by adding a particular path to the base URL that specifies the resource
Standard swagger documentation together with testing environment is provided
All responses are in Json format and use the UTF-8 character encoding

TapHome Core version 2021.3 introduces a new feature: TapHome API via local network. Accessing Core locally decreases communication latency and makes the system independent of internet connection. The specification (authentication, requests, replies) is identical to the cloud version. TapHome API over the local network only supports the HTTP protocol and does not include the Swagger user interface.

Authenticating TapHome API Requests

TapHome TapHome API uses a custom HTTP scheme based on a Basic access authentication. It doesn't require cookies, session identifier nor login pages. TapHome TapHome API however does not use login / password pair, but a shared secret called token.

Custom authentication HTTP header is formed as follows:

Authorization: TapHome {token}

Example of authentication HTTP request:

GET /api/TapHomeApi/v1/location HTTP/1.1
Host: api.taphome.com
Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

Example using curl:

curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://api.taphome.com/api/TapHomeApi/v1/location"

When the system receives an authenticated request, it fetches the token that you claim to have and uses it to identify a TapHome Control unit location. If the token does not match TapHome records, the request is dropped and the system responds with an error message (typically HTTP 401).

Alternatively, it is also possible to put the token into the query parameters (for HTTP GET calls only). We strongly suggest not to provide such urls to third parties because the token may be used to access and control any device exposed by the Control unit.

How to get the token

In the TapHome app, go to Settings → Expose devices → TapHome API. In the context menu (three dots on the top right), use the Create new access token function. Caution - whenever you generate a new token, the original URL commands stop working. Click the arrow next to the token and the wizard will copy it to the clipboard.

In case the token has been compromised and needs to be revoked, a new token can be generated using TapHome. Only one token is ever active.

TapHome API Reference

Get Location Info

Gets Control unit location info. Use this call to check if the location is online.

Variant 1
GET /api/TapHomeApi/v1/location

Parameters: none

Variant 2
POST /api/TapHomeApi/v1/location

Parameters: none

Example response:

{
  "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
  "locationName": "Test Location",
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Discover Devices

Gets devices exposed by the Control unit. For each device a list of value types is provided (containing value type id and value type name). Some of the values may be read-only (e.g. Device Status).

In order to set device values you have to provide the valueTypeId to identify the device property which will be set.

Variant 1
GET /api/TapHomeApi/v1/discovery

Parameters: none

Variant 2
POST /api/TapHomeApi/v1/discovery

Parameters: none

Example response:

{
  "devices": [
    {
      "deviceId": 1,
      "type": "VirtualAnalogOutput",
      "name": "My AO",
      "description": "My AO Description",
      "supportedValues": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus"
        },
        {
          "valueTypeId": 42,
          "valueTypeName": "AnalogOutputValue"
        },
        {
          "valueTypeId": 48,
          "valueTypeName": "SwitchState"
        },
        {
          "valueTypeId": 67,
          "valueTypeName": "AnalogOutputDesiredValue"
        }
      ]
    },
    {
      "deviceId": 2,
      "type": "VirtualBlindGroup",
      "name": "My Blind Group",
      "description": "My Blind Group Description",
      "supportedValues": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus"
        },
        {
          "valueTypeId": 10,
          "valueTypeName": "BlindsSlope"
        },
        {
          "valueTypeId": 46,
          "valueTypeName": "BlindsLevel"
        }
      ]
    }
  ],
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Get Device Value

Gets all current values for a given device and their types. The value elements are comprised of value type id, value type name and the actual value. Some of the values may be read-only (e.g. Device Status).

In order to set device values you have to provide the valueTypeId to identify the device property which will be set. The value type is always a number (double).

Requesting the same value too frequently (less than 500 ms between the requests) may return a cached value instead of fetching each time the current value from the Control unit. Responses with equal timestamp fields refer to the same value. Do not assume the timestamp value is always growing, it should be compared for equality only.

Variant 1
GET /api/CloudApi/v1/getDeviceValue/{deviceId}

Parameters: device id in url path (e. g. “1”)

Variant 2
POST /api/CloudApi/v1/getDeviceValue

Parameters:

{
  "deviceId": 1
}

Example response:

{
  "deviceId": 1,
  "values": [
    {
      "valueTypeId": 7,
      "valueTypeName": "DeviceStatus",
      "value": 0
    },
    {
      "valueTypeId": 22,
      "valueTypeName": "OperationMode",
      "value": 0
    },
    {
      "valueTypeId": 23,
      "valueTypeName": "ManualTimeout",
      "value": 0
    },
    {
      "valueTypeId": 42,
      "valueTypeName": "AnalogOutputValue",
      "value": 1
    },
    {
      "valueTypeId": 48,
      "valueTypeName": "SwitchState",
      "value": 1
    },
    {
      "valueTypeId": 67,
      "valueTypeName": "AnalogOutputDesiredValue",
      "value": 1
    }
  ],
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
403 Forbidden - the device is not exposed
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Get values of multiple devices

Gets all current values for given devices and their types. The response value elements are comprised of Value Type ID, Value Type Name and the actual value. Some values may be read-only (e.g. Device Status). Value Type ID is optional. This function requires Core version 2021.3 or newer.

Consider getting multiple values at once with a single API call to save bandwidth and send a reasonable number of requests to the TapHome API server.

POST /api/CloudApi/v1/getMultipleDevicesValues

Parameters:

{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}

Example response:

{
 "devices": [
    {
      "deviceId": 1,
      "values": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus",
          "value": 0
        }
      ]
    },
    {
      "deviceId": 2,
      "values": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus",
          "value": 0
        },
        {
          "valueTypeId": 10,
          "valueTypeName": "BlindsSlope",
          "value": 1.0
        },
        {
          "valueTypeId": 46,
          "valueTypeName": "BlindsLevel",
          "value": 0.0
        }
      ]
    }
  ],
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
403 Forbidden - the device is not exposed
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Get all values of all devices

Gets all current values of all devices at once. The response value elements consist of a value type id, a value type name, and an actual value. Some values may be read-only (eg Device Status). This feature requires Core version 2021.3 or later.

Consider getting multiple values at once with a single API call to save bandwidth and send a reasonable number of requests to the TapHome API server.

Variant 1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2
POST /api/CloudApi/v1/getAllDevicesValues

Example response:

{
 "devices": [
    {
      "deviceId": 1,
      "values": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus",
          "value": 0
        },
        {
          "valueTypeId": 42,
          "valueTypeName": "AnalogOutputValue",
          "value": 1
        },
        {
          "valueTypeId": 48,
          "valueTypeName": "SwitchState",
          "value": 1
        },
        {
          "valueTypeId": 67,
          "valueTypeName": "AnalogOutputDesiredValue",
          "value": 1
        }
      ]
    },
    {
      "deviceId": 2,
      "values": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus",
          "value": 0
        },
        {
          "valueTypeId": 10,
          "valueTypeName": "BlindsSlope",
          "value": 1.0
        },
        {
          "valueTypeId": 46,
          "valueTypeName": "BlindsLevel",
          "value": 0.0
        }
      ]
    }
  ],
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
403 Forbidden - the device is not exposed
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Get One Device Value

Gets one current value for a given device and value type id as text - it does not require any JSON processing. This function is ideal for simple integrations. Typically, you’d also include the token in the query string as well, so all necessary parameters are provided in the url and setting the HTTP headers is not necessary.

The reply is always a number (double), formatted to string using decimal point and not using any thousand separators nor the scientific notation. If the value is unknown, the reply is NaN.

Requesting the same value too frequently (less than 500 ms between the requests) may return a cached value instead of fetching each time the current value from the Control unit.

GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken}

Parameters: device id in url path (e. g. “1”) query parameters - value type id (e. g. “42”)

Example response:

1.27

Possible HTTP status errors:

401 Unauthorized
403 Forbidden - the device is not exposed
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error

Set Device Value

Sets one or more values of a device with given types. Other device's values stay untouched.

The value type is always a number (double).

Setting the same value too frequently (less than 500 ms between the requests) results into HTTP 503 error.

Variant 1
GET /api/TapHomeApi/v1/setDeviceValue/{deviceId}?valueTypeId={valueTypeId1}&value={value1}&valueTypeId2={valueTypeId2}&value2={value2}&valueTypeId3={valueTypeId3}&value3={value3}&
token={theToken}

Parameters: device id in url path (e.g. “2”) query parameters - up to three values and their types (e.g. valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2)

This function variant is ideal for simple integrations, it does not require any JSON processing. Typically, you’d also include the token in the query string as well, so all necessary parameters are provided in the url and setting the HTTP headers is not necessary.

Variant 2
POST /api/TapHomeApi/v1/setDeviceValue

Parameters:

{
  "deviceId": 2,
  "values": [
    {
      "valueTypeId": 46,
      "value": 0.1
    },
    {
      "valueTypeId": 10,
      "value": 0.2
    }
  ]
}

Example response:

{
  "deviceId": 2,
  "valuesChanged": [
    {
      "typeId": 46,
      "result": "changed"
    },
    {
      "typeId": 10,
      "result": "notchanged"
    },
    {
      "typeId": 7,
      "result": "failed"
    }
  ],
  "timestamp": 855000000000
}

Possible HTTP status errors:

401 Unauthorized
403 Forbidden - the device is not exposed
404 Not Found - the location is not connected to cloud
405 Method Not Allowed - the query or the parameters are invalid
500 Internal Server Error
503 Service not available - too frequent set-value requests. Try again later.