Search
MENU
  • TapHome Apps
  • Expressions
  • System architecture by project type
  • Users and Permissions
  • 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://cloudapi.taphome.com/api/cloudapi/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/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.taphome.com
    Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

    Example using curl:

    curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://cloudapi.taphome.com/api/cloudapi/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 → Token. Clicking the arrow next to the token Guid copies it to the clipboard.

    In case the token has been compromised and has to be revoked, a new token can be generated using the TapHome app. There is always only one token 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/CloudApi/v1/location

    Parameters: none

    Variant 2
    POST /api/CloudApi/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/CloudApi/v1/discovery

    Parameters: none

    Variant 2
    POST /api/CloudApi/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​/getMultipleDevicesValue​s

    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​/getAllDevicesValue​s

    Variant 2
    POST ​/api​/CloudApi​/v1​/getAllDevicesValue​s

    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/CloudApi/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/CloudApi/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.