Kasa Smart™ API Doc V1.0.23
Scroll down for example requests and responses.
Document Version: 1.0.23 Status: Released Released Date: Dec 20th 2018 Last Updated: Aug 19th 2024
Authorization URL: https://api.tplinkra.com API Base URL: https://external-api.tplinkra.com/v1 Email: developers.tpra@tp-link.com
Introduction
Kasa Smart APIs enables access to control an account’s devices over the cloud.
DISCLAIMER This document is currently in a DRAFT status and will change in coming months. We do not guarantee the API will be backwards compatible but we will always keep this in mind for future releases of the API. All API requests need to be authenticated and authorized. Authentication and authorization is implemented using standard OAuth2.0 scheme. This is described in detail in the Authentication section of this document.
Request Object
Header Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
Authorization | header | string | true | Bearer [token] |
Content-Type | header | string | true | application/json |
X-Api-Key | header | string | true | API key issued during OAuth 2.0 registration. |
X-Client-Id | header | string | true | Client ID issued during OAuth 2.0 registration. |
X-Request-Id | header | string | false | A unique id to correlate the request and response. |
Body Parameters
Sample Body parameter
{
"data": {
"powered": true
}
}
All requests which requires body parameters must be a JSON object in the request body. Most of the APIs have a common request format as specified in the example section on the right side. Notice that all request body params have "data" in it, this encapsulates the request data object of the service, that needs to be called. Please use the schema section to determine the correct data object for a service.
Path Parameters
Parameters within the path of the endpoint, before the query string (?). These are set off within curly braces.
Path parameters are part of the endpoint itself and are not optional.
For example, {deviceId} and {scheduleId} are the path parameters in the following endpoint:
GET /devices/{deviceId}/schedules/{scheduleId}
Query String Parameters
Query string parameters appear after a question mark (?) in the endpoint.
The question mark followed by the parameters and their values is referred to as the “query string.”
In the query string, each parameter is listed one right after the other with an ampersand (&) separating them.
The order of the query string parameters does not matter.
For example:
GET /devices/{deviceId}/energy-consumption?month=<xx>&year=<xxxx>
Response Object
200 Sample Response
json { "requestId": "thisissamplerequestid" }
API response is always a JSON object with HTTP Content-Type header as ‘application/json’.
HTTP Status Codes
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | The request has succeeded. | Response |
302 | Found | The target resource resides temporarily under a different URI. | None |
400 | Bad Request | The request could not be understood by the server due to malformed syntax. | Response |
401 | Unauthorized | The request requires user authentication. | Response |
403 | Forbidden | The server understood the request but refuses to authorize it. | Response |
429 | Too Many Requests | The user has sent too many requests in a given amount of time ("rate limiting"). | Response |
500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. | Response |
503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. | Response |
Successful Response
200 Sample Response with data
{
"requestId": "thisisasamplerequestid",
"data": {
"device": {
"id": "thisisasampledeviceid",
"name": "Device name",
"model": "Device model",
"type": "Device Type",
"online": true,
"capability": [
"traits.devices.OnOff",
"traits.devices.Schedule",
"traits.devices.EnergyMonitoring",
"traits.devices.RuntimeStats"
],
"hardwareVersion": "1.0",
"softwareVersion": "1.0.6 Build 180627 Rel.081000"
},
"state": {
"powered": false
}
},
"responseTime": 110
}
Successful response object will always have request ID. Request ID can be system generated or user specified if given in the header request. In case where service is suppose to provide some data; response object will also have a "data" object which is the actual response data for the respective API call.
Error Response
Example Error Response
{
"requestId": "string",
"msg": "string",
"code": "string"
}
Apart from HTTP status codes, in case of any error; response object will contain a custom error code. This will help identifying an issue. It will also contain a user friendly error message indicating what might have go wrong, and with a request ID.
Custom Error Codes
Error Code | Description |
---|---|
GENERAL_EXCEPTION | General Exception |
DEVICE_NOT_RESPONDING | In case of no device heartbeat |
DEVICE_OFFLINE | Device is offline |
UNAUTHORIZED | In case of invalid token or account |
TOO_MANY_REQUESTS | Too many requests |
INVALID_HEADER | Invalid ClientID or ApiKey |
CAPABILITY_NOT_SUPPORTED | Occurs when the device do not support the requested functionality |
INVALID_DEVICE | Invalid Device |
BAD_REQUEST | Can occur when there is invalid Content-Type or invalid argument |
NOT_FOUND | In case when required data is not found |
Authentication
TP-LINK OAuth 2.0 Server acts as an authentication gateway for all IoT APIs exposed by TP-LINK. The server implements the OAuth 2.0 protocol, and is complaint to RFC-6749 specifications. The implementation has support for grant type of Authorization ErrorCode and Refresh Token.
Authorization
The user is presented with a login form with client details, to sign in to an existing TP-LINK cloud account.
Upon successful authentication the OAuth server sends a HTTP 302 redirect to the redirect URL provided by the client during registration with an authorization code.
Authorization Base URL = https://api.tplinkra.com
Request
GET /oauth/authorize?client_id=<CLIENT_ID>&response_type=<code>&state=<CLIENT_STATE>&scope=<device_control>&redirect_uri=<REDIRECT_URI>
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | string | true | CLIENT_ID |
response_type | string | true | code |
state | string | true | CLIENT_STATE |
scope | string | true | device_control |
redirect_uri | string | true | REDIRECT_URI |
Responses
Status | Meaning | Description |
---|---|---|
302 | Found | <REDIRECT_URL>?code=AUTHORIZATION_CODE&state=CLIENT_STATE |
302 | Found | <REDIRECT_URL>?error=ERROR&error_description=ERROR_DESC&state=CLIENT_STAT |
Access Token
200 Sample Response
{
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"token_type": "Bearer",
"expires_in": 2592000
}
Sample Error Response
{
"error_description": "Missing parameters: client_secret",
"error": "invalid_request"
}
Issues an access token for a provided authorization code or refresh token. The issued access token is valid for 15 days
Grant Type: Authorization Code
Request
POST /oauth/access_token?client_id=<CLIENT_ID>&grant_type=authorization_code&code=<AUTHORIZATION_CODE>&redirect_uri=<REDIRECT_URI>&client_secret=<CLIENT_SECRET>
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | string | true | CLIENT_ID |
grant_type | string | true | authorization_code |
code | string | true | AUTHORIZATION_CODE |
redirect_uri | string | true | REDIRECT_URI |
client_secret | string | true | CLIENT_SECRET |
Response
Name | Type | Description |
---|---|---|
access_token | string | none |
refresh_token | string | none |
token_type | string | none |
expires_in | string | none |
Grant Type: Refresh Token
Request
POST /oauth/access_token?client_id=<CLIENT_ID>&grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>&client_secret=<CLIENT_SECRET>
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
Parameter | Type | Required | Description |
---|---|---|---|
client_id | string | true | CLIENT_ID |
grant_type | string | true | refresh_token |
refresh_token | string | true | REFRESH_TOKEN |
client_secret | string | true | CLIENT_SECRET |
Response
Name | Type | Description |
---|---|---|
access_token | string | none |
refresh_token | string | none |
token_type | string | none |
expires_in | string | none |
Unlink
Unlink user's integration with Kasa account, the unlink base URL is API base URL: https://external-api.tplinkra.com/v1
Request
POST /account/unlink
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
None
Sample Response
{
"requestId": "request-id-string",
"data": {},
"responseTime": 110
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Device Discovery
Device Discovery
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"accountId": "thisisasampleaccountid",
"devices": [
{
"id": "thisisasampledeviceid",
"name": "Meeting Room Plug",
"description": "Wi-Fi Smart Plug With Energy Monitoring",
"model": "HS110",
"type": "devices.types.Outlet",
"online": true,
"capability": [
"traits.devices.OnOff",
"traits.devices.EnergyMonitoring",
"traits.devices.Schedule",
"traits.devices.RuntimeStats"
],
"hardwareVersion": "1.0",
"softwareVersion": "1.2.5 Build 171206 Rel.085954",
"macAddress":"TE:ST:MA:CA:DD:R1"
},
{
"id": "thisisanothersampledeviceid",
"name": "Bedroom light",
"description": "Smart Wi-Fi LED Bulb with Color Changing",
"model": "KL130",
"type": "devices.types.Light",
"online": false,
"capability": [
"traits.devices.OnOff",
"traits.devices.Brightness",
"traits.devices.ColorTemperature",
"traits.devices.ColorSpectrum",
"traits.devices.EnergyMonitoring",
"traits.devices.Schedule",
"traits.devices.RuntimeStats"
],
"metadata": {
"minColorTemperature": 2500,
"maxColorTemperature": 9000
},
"hardwareVersion": "1.0",
"softwareVersion": "1.8.6 Build 180809 Rel.091659",
"macAddress":"TE:ST:MA:CA:DD:R2"
}
]
},
"responseTime": 2392
}
Discovery service returns all available devices for an account. List contains device object containing device information. Click on the "Device" link below to get to device schema.
Request
GET /devices
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
accountId | string | Kasa accountId of the user |
devices | [Device] | List of available devices |
responseTime | integer(int32) | API response time in milliseconds |
Device Info
Device Info
Provides device details such as name, type, model, capabilities and device state. Capabilities shows device capability such as energy monitoring support or color spectrum support (in case of smart bulb) etc. Device state provides device current state mode such as if the device is powered or switched off. "Online" status shows if the device is connected or not.
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"device": {
"id": "thisisasampledeviceid",
"name": "Dinning Room Plug",
"description": "Wi-Fi Smart Plug With Energy Monitoring",
"model": "HS110",
"type": "devices.types.Outlet",
"online": true,
"capability": [
"traits.devices.OnOff",
"traits.devices.EnergyMonitoring",
"traits.devices.Schedule",
"traits.devices.RuntimeStats"
],
"hardwareVersion": "1.0",
"softwareVersion": "1.2.5 Build 171206 Rel.085954",
"macAddress":"TE:ST:MA:CA:DD:R3"
},
"state": {
"powered": true
}
},
"responseTime": 399
}
Request
GET /devices/{deviceId}
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
device | Device | Device model for accessing device information |
state | State | State model to change device state |
responseTime | integer(int32) | API response time in milliseconds |
Device Control
Device On/ Off
This API can be used to switch device power ON/ or OFF.
Sample Request
{
"data": {
"powered": true,
"transitionPeriod": 10000
}
}
Request
POST /devices/{deviceId}/power
- Body Parameters
Name | Type | Description |
---|---|---|
powered | boolean | Turn power on/off |
transitionPeriod | integer(int32) | Range: (0-10000) ms |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Sample Response
{
"requestId": "string",
"responseTime": 419
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Change Device Color
Changes device color spectrum. Uses hue, saturation and brightness (HSB) values provided in the API body.
Sample Request
{
"data": {
"color": {
"hsb": {
"hue": 0,
"saturation": 0,
"brightness": 0
}
},
"transitionPeriod": 10000
}
}
Request
POST /devices/{deviceId}/color
- Body Parameters
Name | Type | Description |
---|---|---|
color | Color | Color model for adjusting device color |
transitionPeriod | integer(int32) | Range: (0-10000) ms |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Sample Response
{
"requestId": "string",
"responseTime": 100
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Change Color Temperature
Changes device color temperature based on kelvin value provided in API body.
Sample Request
{
"data": {
"colorTemperature": 0,
"transitionPeriod": 10000
}
}
Request
POST /devices/{deviceId}/color-temperature
- Body Parameters
Name | Type | Description |
---|---|---|
colorTemperature | integer(int32) | Describe the light appearance. It is measured in degrees of Kelvin (K). Use Device Info API to find minimum and maximum range |
transitionPeriod | integer(int32) | Range: (0-10000) ms |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Sample Response
{
"requestId": "string",
"responseTime": 201
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Change Brightness
Change or dim device brightness.
Sample Request
{
"data": {
"brightness": 0,
"transitionPeriod": 10000
}
}
Request
POST /devices/{deviceId}/brightness
- Body Parameters
Name | Type | Description |
---|---|---|
brightness | integer(int32) | Range: (0-100) |
transitionPeriod | integer(int32) | Range: (0-10000) ms |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Sample Response
{
"requestId": "string",
"responseTime": 211
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Energy Consumption
Energy Consumption by Day
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"energyStats": [
{
"day": 1,
"energyWattHour": 57
},
{
"day": 2,
"energyWattHour": 58
},
{
"day": 3,
"energyWattHour": 57
},
{
"day": 4,
"energyWattHour": 58
},
{
"day": 5,
"energyWattHour": 58
},
{
"day": 6,
"energyWattHour": 57
},
{
"day": 7,
"energyWattHour": 58
},
{
"day": 8,
"energyWattHour": 26
}
]
},
"responseTime": 529
}
Provides energy usage aggregated by day. For energy usage aggregated by day we support only past 30 days of data. So if you are in the middle of the month, previous months data will only show days which lie within past 30 days. See examples below,
Case: 1 Today is March 1st 2019, and I want February 2019 data Request: /devices/{deviceId}/energy-consumption?month=2&year=2019&groupBy=day Response: Day 1 to Day 28 of February data.
Case: 2 Today is March 1st 2019, and I want January 2019 data Request: /devices/{deviceId}/energy-consumption?month=1&year=2019&groupBy=day Response: Day 31st of January data only.
Case: 3 Today is March 1st 2019, and I want March 2019 data Request: /devices/{deviceId}/energy-consumption?month=3&year=2019&groupBy=day Response: Day 1st of March data only.
Request
GET /devices/{deviceId}/energy-consumption?month=<xx>&year=<xxxx>&groupBy=day
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
Parameter | Type | Required | Description |
---|---|---|---|
month | int | true | Month number |
year | int | true | Year |
groupBy | string | true | day |
Response
Name | Type | Description |
---|---|---|
energyStats | [EnergyStats] | [List of Energy statistics of a device] |
responseTime | integer(int32) | API response time in milliseconds |
Energy Consumption by Month
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"energyStats": [
{
"month": 3,
"energyWattHour": 57
},
{
"month": 4,
"energyWattHour": 58
},
{
"month": 5,
"energyWattHour": 57
},
{
"month": 6,
"energyWattHour": 58
},
{
"month": 7,
"energyWattHour": 58
},
{
"month": 8,
"energyWattHour": 57
},
{
"month": 9,
"energyWattHour": 58
},
{
"month": 10,
"energyWattHour": 26
},
{
"month": 11,
"energyWattHour": 58
},
{
"month": 12,
"energyWattHour": 26
}
]
},
"responseTime": 429
}
Provides energy usage aggregated by month. For energy usage aggregated by month we support only past 12 months of data. Month is optional, in case if month is not provided for the year it will show all months which lie within the past 12 months of the specified year. See examples below,
Case: 1 Current month/ year is February 2019, and I want 2018 monthly data Request: /devices/{deviceId}/energy-consumption?year=2018&groupBy=month Response: March to December 2018 data only.
Case: 2 Current month/ year is February 2019, and I want September 2018 data Request: /devices/{deviceId}/energy-consumption?month=9&year=2018&groupBy=month Response: September 2018 data only.
Case: 3 Current month/ year is June 2019, and I want 2019 data Request: /devices/{deviceId}/energy-consumption?year=2019&groupBy=month Response: January to June 2019 data only.
Request
GET /devices/{deviceId}/energy-consumption?month=<xx>&year=<xxxx>&groupBy=month
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
Parameter | Type | Required | Description |
---|---|---|---|
month | int | true | Month number |
year | int | true | Year |
groupBy | string | true | month |
Response
Name | Type | Description |
---|---|---|
energyStats | [EnergyStats] | [List of Energy statistics of a device] |
responseTime | integer(int32) | API response time in milliseconds |
Delete All Energy Stats
Erases all previous energy consumption stats of the device.
Request
DELETE /devices/{deviceId}/energy-consumption
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
200 Sample Response
{
"requestId": "string",
"responseTime": 112
}
Get Real Time Energy Stats
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"realTimeStat": {
"currentAmps": 0.077109,
"VoltageVolts": 120.331222,
"powerWatts": 8.589514,
"totalKWs": 2.367
}
},
"responseTime": 538
}
Provides real time energy usage.
Request
GET /devices/{deviceId}/realtime-energy-consumption
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
realTimeStat | RealTimeStat | Real Time Energy Stat |
responseTime | integer(int32) | API response time in milliseconds |
Energy Specific Error Codes
Error Code | Description |
---|---|
OUT_OF_RANGE_EXCEPTION | When year/ month in request is either in future or too old |
Runtime
Get Runtime by Day
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"runtimeStats": [
{
"day": 1,
"usageMins": 1440
},
{
"day": 2,
"usageMins": 1054
},
{
"day": 3,
"usageMins": 0
},
{
"day": 4,
"usageMins": 565
},
{
"day": 5,
"usageMins": 1440
},
{
"day": 6,
"usageMins": 1439
},
{
"day": 7,
"usageMins": 1440
}
]
},
"responseTime": 538
}
Provides runtime (usage) aggregated by day. For runtime usage aggregated by day we support only past 30 days of data. So if you are in the middle of the month, previous months data will only show days which lie within past 30 days. See examples below,
Case: 1 Today is March 1st 2019, and I want February 2019 data Request: /devices/{deviceId}/runtime?month=2&year=2019&groupBy=day Response: Day 1 to Day 28 of February data.
Case: 2 Today is March 1st 2019, and I want January 2019 data Request: /devices/{deviceId}/runtime?month=1&year=2019&groupBy=day Response: Day 31st of January data only.
Case: 3 Today is March 1st 2019, and I want March 2019 data Request: /devices/{deviceId}/runtime?month=3&year=2019&groupBy=day Response: Day 1st of March data only.
Request
GET /devices/{deviceId}/runtime?month=<xx>&year<xxxx>&groupBy=day
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
month | query | int | true | Month number |
year | query | int | true | Year |
groupBy | query | string | true | day |
Response
Name | Type | Description |
---|---|---|
runtimeStats | [RuntimeStat] | List of Device usage statistics |
responseTime | integer(int32) | API response time in milliseconds |
Get Runtime by Month
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"energyStats": [
{
"month": 3,
"usageMins": 57
},
{
"month": 4,
"usageMins": 58
},
{
"month": 5,
"usageMins": 57
},
{
"month": 6,
"usageMins": 58
},
{
"month": 7,
"usageMins": 58
},
{
"month": 8,
"usageMins": 57
},
{
"month": 9,
"usageMins": 58
},
{
"month": 10,
"usageMins": 26
},
{
"month": 11,
"usageMins": 58
},
{
"month": 12,
"usageMins": 26
}
]
},
"responseTime": 538
}
Provides runtime (usage) aggregated by month. For runtime usage aggregated by month we support only past 12 months of data. Month is optional, in case if month is not provided for the year it will show all months which lie within the past 12 months of the specified year. See examples below,
Case: 1 Current month/ year is February 2019, and I want 2018 monthly data Request: /devices/{deviceId}/runtime?year=2018&groupBy=month Response: March to December 2018 data only.
Case: 2 Current month/ year is February 2019, and I want September 2018 data Request: /devices/{deviceId}/runtime?month=9&year=2018&groupBy=month Response: September 2018 data only.
Case: 3 Current month/ year is June 2019, and I want 2019 data Request: /devices/{deviceId}/runtime?year=2019&groupBy=month Response: January to June 2019 data only.
Request
GET /devices/{deviceId}/runtime?month=<xx>&year<xxxx>&groupBy=month
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
month | query | int | true | Month number |
year | query | int | true | Year |
groupBy | query | string | true | month |
Response
Name | Type | Description |
---|---|---|
runtimeStats | [RuntimeStat] | [List of Energy statistics of a device] |
responseTime | integer(int32) | API response time in milliseconds |
Runtime Specific Error Codes
Error Code | Description |
---|---|
OUT_OF_RANGE_EXCEPTION | When year/ month in request is either in future or too old |
Schedule
Get All Schedules
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"schedules": [
{
"id": "thisisasamplescheduleid",
"name": "Turn on",
"enabled": true,
"frequency": {
"repeating": {
"weekdays": [
"MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"
],
"timeOfDay": "1800"
}
},
"state": {
"powered": true
},
"timeOption": "TIME"
},
{
"id": "anothersamplescheduleid",
"name": "Turn off",
"enabled": true,
"frequency": {
"oneTime": {
"scheduleTime": "2018-12-27T07:00"
}
},
"state": {
"powered": false
},
"timeOption": "TIME"
}
]
},
"responseTime": 538
}
List all schedules of a device.
Request
GET /devices/{deviceId}/schedules
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
schedules | [Schedule] | List of schedules |
responseTime | integer(int32) | API response time in milliseconds |
Get a Schedule
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"schedule": {
"id": "anothersamplescheduleid",
"name": "Turn off",
"enabled": true,
"frequency": {
"oneTime": {
"scheduleTime": "2019-01-27T07:00"
}
},
"state": {
"powered": false
},
"timeOption": "TIME"
}
},
"responseTime": 538
}
Gets a schedule of a device.
Request
GET /devices/{deviceId}/schedules/{scheduleId}
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
scheduleId | string | Schedule ID for accessing schedule |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
schedule | Schedule | Schedule object |
responseTime | integer(int32) | API response time in milliseconds |
Create Schedule
200 Sample Request Payload
{
"data": {
"schedule": {
"name": "Turn on Lights",
"enabled": true,
"frequency": {
"repeating": {
"weekdays": [
"MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"
],
"timeOfDay": "1800"
}
},
"state": {
"powered": true,
"color": {
"hsb": {
"hue": 100,
"saturation": 100,
"brightness": 100
}
},
"colorTemperature": 4500,
"mode": "CUSTOMIZE_PRESET",
"brightness": 100
},
"timeOption": "TIME"
}
}
}
200 Sample Response
{
"requestId": "thisisasamplerequestid",
"data": {
"schedule": {
"id": "newscheduleid"
}
},
"responseTime": 538
}
Schedules an action on a device.
Request
POST /devices/{deviceId}/schedules
- Body Parameters
Name | Type | Required | Description |
---|---|---|---|
schedule | Schedule | true | Schedule without ID |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
schedule | Schedule | New Schedule with ID |
responseTime | integer(int32) | API response time in milliseconds |
Update Schedule
200 Sample Request Payload
{
"data": {
"schedule": {
"id": "thisisasamplescheduleid",
"name": "Updated Name",
"enabled": true,
"frequency": {
"oneTime": {
"scheduleTime": "2019-12-31T19:05"
}
},
"state": {
"powered": true
},
"timeOption": "TIME"
}
}
}
Update existing schedule of a device.
Request
POST /devices/{deviceId}/schedules/{scheduleId}
- Body Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
schedule | Schedule | body | true | Schedule with ID |
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
scheduleId | string | Schedule ID for accessing schedule |
- Query String Parameters
None
Sample Response
{
"requestId": "string",
"responseTime": 538
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Remove all schedules
Removes all schedules of a device.
Request
DELETE /devices/{deviceId}/schedules
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
200 Sample Response
{
"requestId": "string",
"responseTime": 538
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Remove a schedule
Removes schedule from a device.
Request
DELETE /devices/{deviceId}/schedules/{scheduleId}
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
scheduleId | string | Schedule ID for accessing schedule |
- Query String Parameters
None
200 Sample Response
{
"requestId": "string",
"responseTime": 538
}
Response
Name | Type | Description |
---|---|---|
requestId | string | API request ID |
responseTime | integer(int32) | API response time in milliseconds |
Get Next/ Upcoming Schedule
Gets the next upcoming schedule of a device.
200 Example Response
{
"requestId": "thisisasamplerequestid",
"data": {
"schedule": {
"id": "thisisasamplescheduleid",
"name": "Next Schedule",
"enabled": true,
"frequency": {
"repeating": {
"weekdays": [
"FRIDAY"
],
"timeOfDay": "0128"
}
},
"state": {
"powered": false
},
"timeOption": "TIME"
}
},
"responseTime": 538
}
Request
GET /devices/{deviceId}/schedules/next
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
schedule | Schedule | Next Schedule |
responseTime | integer(int32) | API response time in milliseconds |
Schedule Specific Error Codes
Error Code | Description |
---|---|
SCHEDULE_CONFLICT | When another schedule running at the same time |
Timezone
Account Timezone
Retrieves account timezone.
Example responses
200 Response
{
"data": {
"timezoneId": "string"
},
"responseTime": 56
}
Request
GET /account/timezone
- Body Parameters
None
- Path Parameters
None
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
timezoneId | string | Accounts Timezone ID |
responseTime | integer(int32) | API response time in milliseconds |
Device Timezone
Retrieve device timezone
Example responses
200 Response
{
"data": {
"timezoneId": "string"
},
"responseTime": 56
}
Request
GET /devices/{deviceId}/timezone
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
timezoneId | string | Accounts Timezone ID |
responseTime | integer(int32) | API response time in milliseconds |
Sync Device Timezone
Overwrite device timezone information with account timezone configuration. Account timezoneId is returned in the response.
Example responses
200 Response
{
"data": {
"timezoneId": "string"
},
"responseTime": 56
}
Request
POST /devices/{deviceId}/timezone
- Body Parameters
None
- Path Parameters
Name | Type | Description |
---|---|---|
deviceId | string | Device ID for accessing device |
- Query String Parameters
None
Response
Name | Type | Description |
---|---|---|
timezoneId | string | Accounts Timezone ID |
responseTime | integer(int32) | API response time in milliseconds |
Schemas
Success Response
{
"requestId": "string"
}
Properties
Name | Type | Description |
---|---|---|
requestId | string | none |
Error Response
{
"requestId": "string",
"msg": "string",
"code": "string"
}
Properties
Name | Type | Description |
---|---|---|
requestId | string | none |
msg | string | Error message |
code | string | Error code |
Power
{
"powered": true
}
Properties
Name | Type | Description |
---|---|---|
powered | boolean | none |
Color
{
"hsb": {
"hue": 0,
"saturation": 0,
"brightness": 0
}
}
Color model for adjusting device color
Properties
Name | Type | Description |
---|---|---|
hsb | HSB | Hue, Saturation, Brightness (color model) for adjusting device color |
HSB
{
"hue": 0,
"saturation": 0,
"brightness": 0
}
Hue, Saturation, Brightness (color model) for adjusting device color
Properties
Name | Type | Required | Description |
---|---|---|---|
hue | number(double) | true | Range: (0-360) |
saturation | number(double) | true | Range: (0-100) |
brightness | integer(int32) | true | Range: (0-100) |
Color Temperature
{
"colorTemperature": 0
}
Properties
Name | Type | Description |
---|---|---|
colorTemperature | integer(int32) | Describe the light appearance. It is measured in degrees of Kelvin (K). Use Device Info API to find minimum and maximum range |
Brightness
{
"brightness": 0
}
Properties
Name | Type | Description |
---|---|---|
brightness | integer(int32) | Range: (0-100) |
Device
{
"id": "string",
"name": "string",
"description": "string",
"model": "string",
"type": "string",
"online": true,
"capability": [
"string"
],
"metadata": {
"minColorTemperature": 0,
"maxColorTemperature": 0
},
"hardwareVersion": "string",
"softwareVersion": "string"
}
Device model for accessing device information
Properties
Name | Type | Description |
---|---|---|
id | string | Device ID |
name | string | Device name |
description | string | Description |
model | string | The model number with region – HS100(US) or HS100(EU) |
type | Type | A unique key for identifying the device type. |
online | boolean | Device connection status |
capability | [Capability] | List of device capabilities |
metadata | DeviceMeta | Device meta information |
hardwareVersion | string | Device hardware version |
softwareVersion | string | Device software version |
macAddress | string | Mac Address of the device |
Device Type
{
"type": "string"
}
Supported device types
Properties
Name | Type | Description |
---|---|---|
devices.types.Light | string | Smart Bulbs |
devices.types.Outlet | string | Smart Plugs |
devices.types.Switch | string | Smart Switches |
Device Capability
{
"capability": [
"traits.devices.OnOff",
"traits.devices.Brightness",
"traits.devices.ColorTemperature",
"traits.devices.ColorSpectrum",
"traits.devices.EnergyMonitoring",
"traits.devices.Schedule",
"traits.devices.RuntimeStats"
]
}
List of capabilities (list of string) that the device supports
Properties
Name | Type | Description |
---|---|---|
traits.devices.OnOff | string | Power On/Off |
traits.devices.Brightness | string | Change brightness |
traits.devices.ColorTemperature | string | Change color temperature |
traits.devices.ColorSpectrum | string | Change color |
traits.devices.EnergyMonitoring | string | Energy Stats |
traits.devices.Schedule | string | Schedule an action |
traits.devices.RuntimeStats | string | Runtime stats |
Device Meta
{
"minColorTemperature": 0,
"maxColorTemperature": 0
}
Device metadata
Properties
Name | Type | Description |
---|---|---|
minColorTemperature | integer(int32) | Minimum color temperature varies per device, can be used when changing color temperature of a supported device |
maxColorTemperature | integer(int32) | Maximum color temperature varies per device, can be used when changing color temperature of a supported device |
State
{
"powered": true,
"color": {
"hsb": {
"hue": 0,
"saturation": 0,
"brightness": 0
}
},
"colorTemperature": 0,
"mode": "string",
"brightness": 0
}
State model to change device state
Properties
Name | Type | Required | Description |
---|---|---|---|
powered | boolean | true | (On: true, Off: false) |
color | Color | false | Color object |
colorTemperature | integer(int32) | false | Describe the light appearance. It is measured in degrees of Kelvin (K) |
mode | mode | false | Acceptable values: CIRCADIAN, LAST_STATUS, CUSTOMIZE_PRESET |
brightness | integer(int32) | false | Range: (0-100) |
Mode
{
"mode": "string"
}
Use these mode values while setting up schedule for smart bulbs
Properties
Name | Type | Description |
---|---|---|
LAST_STATUS | string | (Default) Last known device state |
CIRCADIAN | string | Circadian rhythms |
CUSTOMIZE_PRESET | string | Custom values for brightness, color, color temperature |
Energy Stats
{
"day": 0,
"month": 0,
"energyWattHour": 0
}
Energy statistics of a device
Properties
Name | Type | Description |
---|---|---|
day | integer(int32) | Day of a month. Only displayed in case of groupBy "day" |
month | integer(int32) | Month of a year. Only displayed in case of groupBy "month" |
energyWattHour | number(double) | Energy stat in wh |
Runtime Stat
{
"day": 0,
"month": 0,
"usageMins": 0
}
Properties
Name | Type | Description |
---|---|---|
day | integer(int32) | Day of a month. Only displayed in case of groupBy "day" |
month | integer(int32) | Month of a year. Only displayed in case of groupBy "month" |
usageMins | number(double) | Device usage in minutes |
Frequency
{
"oneTime": {
"scheduleTime": "string"
},
"repeating": {
"weekdays": [
"string"
],
"timeOfDay": "string"
}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
oneTime | OneTime | false | One time schedule runs on a specific date and time |
repeating | Repeating | false | Repeating schedule runs at given time of day(s) |
OneTime
{
"scheduleTime": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
scheduleTime | string | false | Format: yyyy-MM-ddTHH:mm (User time in ISO-8601) |
Repeating
{
"weekdays": [
"string"
],
"timeOfDay": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
weekdays | [string] | false | SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY |
timeOfDay | string | false | Format: HHmm (24 Hour Clock/ Military Time) |
Schedule
{
"schedule": {
"id": "string",
"name": "string",
"enabled": true,
"frequency": {
"oneTime": {
"scheduleTime": "string"
},
"repeating": {
"weekdays": [
"string"
],
"timeOfDay": "string"
}
},
"state": {
"powered": true,
"color": {
"hsb": {
"hue": 0,
"saturation": 0,
"brightness": 0
}
},
"colorTemperature": 0,
"mode": "string",
"brightness": 0
},
"timeOption": "string"
}
}
Schedule model for managing device schedules
Properties
Name | Type | Required | Description |
---|---|---|---|
id | string | false | Schedule ID |
name | string | false | Name of a schedule, allowed length: 32 characters |
enabled | boolean | false | To enable or disable |
frequency | Frequency | false | Repeating or OneTime |
state | State | false | State object with specific action specified |
timeOption | string | false | Allowed Values: TIME, SUNRISE, SUNSET |
Timezone
{
"timezoneId": "string"
}
Properties
Name | Type | Required | Description |
---|---|---|---|
timezoneId | string | false | Timezone ID Example: "Asia/Shanghai" |
Real time Stat
{
"realTimeStat": {
"currentAmps": 0.077109,
"VoltageVolts": 120.331222,
"powerWatts": 8.589514,
"totalKWs": 2.367
}
}
Properties
Name | Type | Required | Description |
---|---|---|---|
currentAmps | double | false | Current value in Amps |
VoltageVolts | double | false | Voltage value in Volts |
powerWatts | double | true | Power value in Watts |
totalKWs | double | false | Total in kW |