NAV Navbar
JSON Examples

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>

None

None

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>

None

None

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>

None

None

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 user's integration with Kasa account, the unlink base URL is API base URL: https://external-api.tplinkra.com/v1

POST /account/unlink

None

None

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

None

None

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}

None

Name Type Description
deviceId string Device ID for accessing device

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

Name Type Description
powered boolean Turn power on/off
transitionPeriod integer(int32) Range: (0-10000) ms
Name Type Description
deviceId string Device ID for accessing device

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

Name Type Description
color Color Color model for adjusting device color
transitionPeriod integer(int32) Range: (0-10000) ms
Name Type Description
deviceId string Device ID for accessing device

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

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
Name Type Description
deviceId string Device ID for accessing device

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

Name Type Description
brightness integer(int32) Range: (0-100)
transitionPeriod integer(int32) Range: (0-10000) ms
Name Type Description
deviceId string Device ID for accessing device

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

None

Name Type Description
deviceId string Device ID for accessing device
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

None

Name Type Description
deviceId string Device ID for accessing device
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

None

Name Type Description
deviceId string Device ID for accessing device

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

None

Name Type Description
deviceId string Device ID for accessing device

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

None

Name Type Description
deviceId string Device ID for accessing device
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

None

Name Type Description
deviceId string Device ID for accessing device
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

None

Name Type Description
deviceId string Device ID for accessing device

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}

None

Name Type Description
deviceId string Device ID for accessing device
scheduleId string Schedule ID for accessing schedule

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

Name Type Required Description
schedule Schedule true Schedule without ID
Name Type Description
deviceId string Device ID for accessing device

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}

Name Type In Required Description
schedule Schedule body true Schedule with ID
Name Type Description
deviceId string Device ID for accessing device
scheduleId string Schedule ID for accessing schedule

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

None

Name Type Description
deviceId string Device ID for accessing device

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}

None

Name Type Description
deviceId string Device ID for accessing device
scheduleId string Schedule ID for accessing schedule

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

None

Name Type Description
deviceId string Device ID for accessing device

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

None

None

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

None

Name Type Description
deviceId string Device ID for accessing device

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

None

Name Type Description
deviceId string Device ID for accessing device

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
JSON Examples