Device Management

Get device list by user ID

API endpoint

action: device.getDeviceList

Request parameter

Parameter name	Type	Description	Required
uid	String	The user ID assigned by Tuya.	Yes

Sample request

{
	"action": "device.getDeviceList",
	"params": {
		"uid": "ay1578921339405Lr3au"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
sub	Boolean	Indicates whether the device is sub-device. Valid values: true: yes. false: no.
uuid	String	The universally unique identifier (UUID) of a specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
name	String	The name of the device.
ip	String	The IP address of the device.
time_zone	String	The time zone.
create_time	Long	The time when the device is first paired.
update_time	Long	The time when the device status was last updated.
active_time	Long	The time when the device is last paired.
status	List	The status of a DP.

Description of status

Parameter name	Type	Description
code	String	The identifier of a data point (DP).
value	String	The value of a DP.

Get device list by app schema

API endpoint

action: device.getListBySchema

Request parameter

Parameter name	Type	Description	Required
schema	String	The schema of a specified application.	Yes
page_no	Integer	The start page number. This is the first page by default.	Yes
page_size	Integer	The maximum number of entries returned on each page. By default, up to 20 entries can be returned on each page.	No

Sample request

{
	"action": "device.getListBySchema",
	"params": {
		"schema": "testApp"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
total	Long	The total number of entries.
devices	List	The list of devices.

Description of devices

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
sub	Boolean	Indicates whether the device is sub-device. Valid values: true: yes. false: no.
uuid	String	The UUID of a specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
name	String	The name of the device.
ip	String	The IP address of the device.
time_zone	String	The time zone.
create_time	Long	The time when the device is first paired.
update_time	Long	The time when the device status was last updated.
active_time	Long	The time when the device is last paired.
status	List	The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Get device list by product ID

API endpoint

action: device.getListByProduct

Request parameter

Parameter name	Type	Description	Required
product_id	String	The product ID.	Yes
page_no	Integer	The start page number. This is the first page by default.	No
page_size	Integer	The maximum number of entries returned on each page. By default, up to 20 entries can be returned on each page.	No

Sample request

{
	"action": "device.getListByProduct",
	"params": {
		"product_id": "xxxxx"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
total	Long	The total number of entries.
devices	List	The list of devices.

Description of devices

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
sub	Boolean	Indicates whether the device is sub-device. Valid values: true: yes. false: no.
uuid	String	The UUID of a specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
name	String	The name of the device.
ip	String	The IP address of the device.
time_zone	String	The time zone.
create_time	Long	The time when the device is first paired.
update_time	Long	The time when the device status was last updated.
active_time	Long	The time when the device is last paired.
status	List	The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Get device list by device ID

API endpoint

action: device.getListByIds

Request parameter

Parameter name	Type	Description	Required
device_ids	String	A list of device IDs.	Yes

Sample request

{
	"action": "device.getListByIds",
	"params": {
		"device_ids": "vdevo15xxxx88132,vdevo1xxx188132"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
total	Long	The total number of entries.
devices	List	The list of devices.

Description of devices

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
sub	Boolean	Indicates whether the device is sub-device. Valid values: true: yes. false: no.
uuid	String	The UUID of a specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
name	String	The name of the device.
ip	String	The IP address of the device.
time_zone	String	The time zone.
create_time	Long	The time when the device is first paired.
update_time	Long	The time when the device status was last updated.
active_time	Long	The time when the device is last paired.
status	List	The status of a DP.

Sample response

{
  "success": true,
  "result": {
  "id": "vdevo153490924188132",
  "uid": "ay1485177979114baBn2",
  "category": "pc",
  "sub": false,
  "uuid": "vdevo153490924188132",
  "online": true,
  "status": [
   {
   "code": "switch_1",
   "value": "false",
   "mode": "rw"
   },
   {
   "code": "countdown_led",
   "value": "0",
   "mode": "rw"
   }
  ],
  "local_key": "aeb4ddbcc34cf26a",
  "product_id": "5T63equBYIDPmGXH",
  "owner_id": "703028"
  }
}

Send instructions to device

API endpoint

action:  device.control

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
commands	Object	The instruction set.	Yes

Sample request

{
	"action": "device.control",
	"params": {
		"device_id": "vdevo158132564936223",
		"commands": [
		{
			"code": "switch_led",
			"value": true
		}
		]
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Get latest device status

API endpoint

action:  device.status

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "device.status",
	"params": {
		"device_id": "vdevo158346027181013"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response

{
	"result": [{
		"code": "switch_led",
		"value": true
	}, {
		"code": "work_mode",
		"value": "white"
	}, {
		"code": "bright_value_v2",
		"value": 370
	}, {
		"code": "temp_value_v2",
		"value": 216
	}, {
		"code": "scene_data_v2",
		"value": ""
	}, {
		"code": "countdown_1",
		"value": 0
	}, {
		"code": "control_data",
		"value": "{\"bright\":370,\"change_mode\":\"gradient\",\"h\":0,\"s\":0,\"temperature\":216,\"v\":0}"
	}],
	"success": true,
	"t": 1583740617030
}

Get instruction set by category

API endpoint

action:  device.functionsByCategory

Request parameter

Parameter name	Type	Description	Required
category	String	The name of the target category. Example: kg, cz, and dj.	Yes

Sample request

{
	"action": "device.functionsByCategory",
	"params": {
		"category": "dj"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
category	String	The product category.
functions	List	The instruction set.

Description of functions

Parameter name	Type	Description
code	String	The DP code.
type	String	The type of DP.
values	String	The range of DP values.
name	String	The name of the DP.
desc	String	The description of the DP.

Sample response

{
  "success": true,
  "t": 1571293457435,
  "result": {
  "category": "kg",
  "functions": [
   {
   "name": "Switch",
   "desc": "The main switch. true: turns all on. false: turns all off.",
   "code": "switch",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 1",
   "desc": "Switch 1",
   "code": "switch_1",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 2",
   "desc": "Switch 2",
   "code": "switch_2",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 3",
   "desc": "Switch 3",
   "code": "switch_3",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 4",
   "desc": "Switch 4",
   "code": "switch_4",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 5",
   "desc": "Switch 5",
   "code": "switch_5",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Switch 6",
   "desc": "Switch 6",
   "code": "switch_6",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "Countdown of Switch 1",
   "desc": "Countdown of Switch 1",
   "code": "countdown_1",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 2",
   "desc": "Countdown of Switch 2",
   "code": "countdown_2",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 3",
   "desc": "Countdown of Switch 3",
   "code": "countdown_3",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 4",
   "desc": "Countdown of Switch 4",
   "code": "countdown_4",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 5",
   "desc": "Countdown of Switch 5",
   "code": "countdown_5",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of Switch 6",
   "desc": "Countdown of Switch 6",
   "code": "countdown_6",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of USB 1",
   "desc": "Countdown of USB 1",
   "code": "countdown_usb1",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "Countdown of USB 2",
   "desc": "Countdown of USB 2",
   "code": "countdown_usb2",
   "type": "Integer",
   "values": "{\"unit\":\"s\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1}"
   },
   {
   "name": "USB1",
   "desc": "USB1",
   "code": "switch_usb1",
   "type": "Boolean",
   "values": "{}"
   },
   {
   "name": "USB2",
   "desc": "USB2",
   "code": "switch_usb2",
   "type": "Boolean",
   "values": "{}"
   }
  ]
  }
}

Get instruction set supported by device

API endpoint

action:  device.functions

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "device.functions",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
category	String	The product category.
functions	List	The instruction set.

Description of functions

Parameter name	Type	Description
code	String	The DP code.
type	String	The type of DP.
values	String	The range of DP values.
name	String	The name of the DP.
desc	String	The description of the DP.

Sample response

{
    "success": true,
    "t": 1571293457435,
    "result": {
        "category": "kg",
        "functions": [
             {
                "name": "Switch",
                "desc": "The main switch. true: turns all on. false: turns all off.",
                "code": "switch",
                "type": "Boolean",
                "values": "{}"
             },
             {
                "name": "Switch 1",
                "desc": "Switch 1",
                "code": "switch_1",
                "type": "Boolean",
                "values": "{}"
             }
        ]
    }
}

Get instruction set and status set supported by device

API endpoint

action:  device.specifications

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "device.specifications",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
category	String	The product category.
functions	List	The instruction set.
status	List	The status set.

Description of functions

Parameter name	Type	Description
code	String	The DP code.
type	String	The type of DP.
values	String	The range of DP values.

Description of status

Parameter name	Type	Description
code	String	The status code.
type	String	The type of DP.
values	String	The range of DP values.

Sample response

{
  "success":true,
  "t":1571201730542,
  "result":{
  "category":"dj",
  "functions":[
   {
   "code":"switch_led",
   "type":"Boolean",
   "values":"{}"
   },
   {
   "code":"work_mode",
   "type":"Enum",
   "values":"{\"range\":[\"colour\"]}"
   },
   {
   "code":"bright_value",
   "type":"Integer",
   "values":"{\"min\":0,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}"
   },
   {
   "code":"colour_data",
   "type":"Json",
   "values":"{\"h\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":360,\"step\":1},\"s\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1},\"v\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}}"
   }
  ],
  "status":[
   {
   "code":"switch_led",
   "type":"Boolean",
   "values":"{}"
   },
   {
   "code":"work_mode",
   "type":"Enum",
   "values":"{\"range\":[\"colour\"]}"
   },
   {
   "code":"bright_value",
   "type":"Integer",
   "values":"{\"min\":0,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}"
   },
   {
   "code":"colour_data",
   "type":"Json",
   "values":"{\"h\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":360,\"step\":1},\"s\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1},\"v\":{\"min\":1,\"scale\":0,\"unit\":\"\",\"max\":255,\"step\":1}}"
   }
  ]
  }
}

Get device details

API description

Query the details of a device, including the properties and latest status of the device.

API endpoint

action:  device.details

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
	"action": "device.details",
	"params": {
		"device_id": "vdevo158132564936223"
	}
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
sub	Boolean	Indicates whether the device is sub-device. Valid values: true: yes. false: no.
uuid	String	The UUID of a specified device.
owner_id	String	The home ID.
online	Boolean	Indicates whether the device is online.
status	Object	The status of a DP.

Description of status

Parameter name	Type	Description
code	String	The identifier of a DP.
value	String	The value of a DP.
type	String	The type of DP.