TapHome

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.

Security note: The local network API and the webhook run over plain HTTP and assume the local network is trusted. On shared or multi-tenant sites — for example hotels or offices with guest Wi-Fi — place the Core on a dedicated network segment separated from the guest network. See Network architecture.

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.

Sent directly, not through the cloud: The webhook is an outbound HTTP POST that the Core sends straight to the configured URL — the payload never passes through the TapHome cloud servers. If the target runs on the same local network, the webhook is delivered locally over the LAN, with no internet round-trip. The Cloud access and Local access switches on the Expose devices page gate only inbound API calls to the Core; they do not turn the webhook off.

Throttling: Changes are batched and sent after approximately 350 ms at the earliest. 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.