--- title: "TapHome API" description: "Integrate TapHome devices into any app using the REST API. Authentication, device control, webhooks, and Swagger documentation." url: "https://taphome.com/en/docs/expose-devices/taphome-api/" language: en lastmod: 2026-11-06 generator: hugo ai: topics: ["rest-api","api-integration","device-control","authentication","webhook","smart-home-api"] questions: ["Where do I find my TapHome API token in the app?","How do I authenticate requests to TapHome API?","What is the base URL for TapHome cloud API?","How to get all device values in a single API request?","How to set up webhook notifications for device changes?","Does the webhook work without cloud access, over the local network only?","What Core firmware version is required for local network API?","What rate limits apply to TapHome API setDeviceValue endpoint?"] --- # TapHome API Using TapHome API it is possible to integrate TapHome devices into any 3rd party application. For example Apple Siri voice control. Last updated: 2026-11-06 TapHome API is an HTTP interface with JSON responses that lets a third-party application read and change the values of TapHome devices. It works with the devices you expose in the TapHome app and offers endpoints for discovery, reading values and setting values, plus a webhook that sends state changes to a URL you configure. You need an access token, which you generate in the TapHome app under **Settings → Expose devices → TapHome API** and send in the Authorization header of every request. The result is that an external application can monitor and control the exposed devices through `https://api.taphome.com/api/TapHomeApi/v1/` or, where the Core supports it, over the local network. ## 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 or newer) 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](https://taphome.com/en/docs/configuration/network-architecture/#local-connection). ## Authentication TapHome API employs custom HTTP authentication using bearer tokens (not username/password credentials). ### Header Format ```text Authorization: TapHome {token} ``` ### Example Request ```text GET /api/TapHomeApi/v1/location HTTP/1.1 Host: api.taphome.com Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32 ``` ### cURL Example ```text 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** ```text GET /api/TapHomeApi/v1/location ``` **Variant 2** ```text POST /api/TapHomeApi/v1/location ``` **Parameters**: None **Response**: ```json { "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** ```text GET /api/TapHomeApi/v1/discovery ``` **Variant 2** ```text POST /api/TapHomeApi/v1/discovery ``` **Parameters**: None **Response**: ```json { "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** ```text GET /api/CloudApi/v1/getDeviceValue/{deviceId} ``` **Variant 2** ```text POST /api/CloudApi/v1/getDeviceValue ``` **Parameters**: Device ID in URL path or JSON body **Response**: ```json { "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 newer. ```text POST /api/CloudApi/v1/getMultipleDevicesValues ``` **Parameters**: ```json { "devices": [ { "deviceId": 1, "valueTypeId": 7 }, { "deviceId": 2 } ], "timestamp": 855000000000 } ``` **Response**: ```json { "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 newer. **Variant 1** ```text GET /api/CloudApi/v1/getAllDevicesValues ``` **Variant 2** ```text POST /api/CloudApi/v1/getAllDevicesValues ``` **Response**: ```json { "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. ```text GET /api/CloudApi/v1/getOneDeviceValue/{deviceId}?valueTypeId={valueTypeId}&token={theToken} ``` **Parameters**: Device ID in path, value type ID and token in query string **Response**: ```text 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** ```text 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** ```text POST /api/TapHomeApi/v1/setDeviceValue ``` **Parameters**: ```json { "deviceId": 2, "values": [ { "valueTypeId": 46, "value": 0.1 }, { "valueTypeId": 10, "value": 0.2 } ] } ``` **Response**: ```json { "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.