Expose Devices

TapHome API

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

Overview

TapHome API enables integration of TapHome devices into third-party applications through HTTP protocol requests and JSON responses. The system operates via https://api.taphome.com/api/TapHomeApi/v1/

Key characteristics include:

HTTP-based resource access with appropriate status codes
Standard Swagger documentation available at https://api.taphome.com/api/doc
UTF-8 encoded JSON responses
Local network API support (Core 2021.3+) via HTTP without Swagger UI

Local Network Advantage: Direct LAN/VPN access reduces latency and eliminates internet dependency. Core units require fixed IP or mDNS configuration.

Authentication

TapHome API employs custom HTTP authentication using bearer tokens (not username/password credentials).

Header Format

1
Authorization: TapHome {token}

Example Request

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

cURL Example

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

Token Management

Locate tokens in TapHome app: Settings → Expose devices → TapHome API

Use context menu (three dots) to generate fresh access tokens. Generating new tokens invalidates previous ones. Query parameter alternative available for GET calls only (security warning: avoid sharing URLs containing tokens).

Compromised tokens require immediate regeneration; only one token remains active simultaneously.

API Reference

Get Location Info

Retrieves Control unit location metadata and validates connectivity status.

Variant 1

1
GET /api/TapHomeApi/v1/location

Variant 2

1
POST /api/TapHomeApi/v1/location

Parameters: None

Response:

1
2
3
4
5
{
  "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
  "locationName": "Test Location",
  "timestamp": 855000000000
}

HTTP Status Errors:

401 Unauthorized
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Discover Devices

Retrieves exposed devices and their supported value types, including read-only properties like Device Status.

Variant 1

1
GET /api/TapHomeApi/v1/discovery

Variant 2

1
POST /api/TapHomeApi/v1/discovery

Parameters: None

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "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
}

HTTP Status Errors:

401 Unauthorized
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Get Device Value

Retrieves all current values for a specified device, including type IDs and names. Values are numeric (double type). Some properties are read-only.

Frequent requests (under 500ms intervals) may return cached values; compare timestamps for equality only.

Variant 1

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

Variant 2

1
POST /api/CloudApi/v1/getDeviceValue

Parameters: Device ID in URL path or JSON body

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "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
}

HTTP Status Errors:

401 Unauthorized
403 Forbidden (device not exposed)
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Get Values of Multiple Devices

Retrieves all current values for multiple devices simultaneously. Reduces bandwidth consumption versus individual requests. Requires Core 2021.3 or later.

1
POST /api/CloudApi/v1/getMultipleDevicesValues

Parameters:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
 "devices": [
    {
      "deviceId": 1,
      "valueTypeId": 7
    },
    {
      "deviceId": 2
    }
  ],
  "timestamp": 855000000000
}

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
 "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
}

HTTP Status Errors:

401 Unauthorized
403 Forbidden (device not exposed)
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Get All Values of All Devices

Retrieves complete state information for all exposed devices in a single request. Requires Core 2021.3 or later.

Variant 1

1
GET /api/CloudApi/v1/getAllDevicesValues

Variant 2

1
POST /api/CloudApi/v1/getAllDevicesValues

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
 "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
}

HTTP Status Errors:

401 Unauthorized
403 Forbidden (device not exposed)
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Get One Device Value

Retrieves a single device value without JSON processing requirements. Ideal for simple implementations. Numeric response (double) formatted as string with decimal point notation.

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

Parameters: Device ID in path, value type ID and token in query string

Response:

1
1.27

Unknown values return NaN. Frequent requests (under 500ms) may return cached data.

HTTP Status Errors:

401 Unauthorized
403 Forbidden (device not exposed)
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error

Set Device Value

Modifies one or more device values by type identifier. Unspecified values remain unchanged. Numeric type (double).

Frequent modifications (under 500ms intervals) produce HTTP 503 response.

Variant 1

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

Supports up to three simultaneous value assignments.

Variant 2

1
POST /api/TapHomeApi/v1/setDeviceValue

Parameters:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "deviceId": 2,
  "values": [
    {
      "valueTypeId": 46,
      "value": 0.1
    },
    {
      "valueTypeId": 10,
      "value": 0.2
    }
  ]
}

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "deviceId": 2,
  "valuesChanged": [
    {
      "typeId": 46,
      "result": "changed"
    },
    {
      "typeId": 10,
      "result": "notchanged"
    },
    {
      "typeId": 7,
      "result": "failed"
    }
  ],
  "timestamp": 855000000000
}

HTTP Status Errors:

401 Unauthorized
403 Forbidden (device not exposed)
404 Not Found (location disconnected from cloud)
405 Method Not Allowed
500 Internal Server Error
503 Service Unavailable (excessive set-value frequency; retry later)

Webhook

Webhook functionality delivers exposed device state changes via HTTP POST to a configured URL within LAN or internet environments. Enables efficient synchronization compared to periodic polling.

Throttling: Activates at maximum intervals of 300ms. Rapid value transitions send only the latest change; earlier intermediate values are discarded. Failed transmissions are not retried.

Configuration: TapHome app supports three custom HTTP request headers in “key: value” format.

Data Structure: Identical to getMultipleDevicesValues endpoint response format.