TapHome API Documentation#

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#

Authorization: TapHome {token}

Example Request#

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

cURL Example#

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

GET /api/TapHomeApi/v1/location

Variant 2

POST /api/TapHomeApi/v1/location

Parameters: None

Response:

{
  "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

GET /api/TapHomeApi/v1/discovery

Variant 2

POST /api/TapHomeApi/v1/discovery

Parameters: None

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
}

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

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

Variant 2

POST /api/CloudApi/v1/getDeviceValue

Parameters: Device ID in URL path or JSON body

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
}

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.

POST /api/CloudApi/v1/getMultipleDevicesValues

Parameters:

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

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
}

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

GET /api/CloudApi/v1/getAllDevicesValues

Variant 2

POST /api/CloudApi/v1/getAllDevicesValues

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
}

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.

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

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

POST /api/TapHomeApi/v1/setDeviceValue

Parameters:

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

Response:

{
  "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.

Backward Expose Devices TapHome to Amazon Alexa Forward