Device Management

Last Updated on : 2024-09-10 01:49:16download

This topic describes the API operations that are used to manage devices.

API list

Request method	API	Description
GET	/v1.0/devices/{device_id}	Get device details
GET	/v1.0/devices/{device_id}/logs	Query device logs
PUT	/v1.0/devices/{device_id}/reset-factory	Restore to factory defaults
DELETE	/v1.0/devices/{device_id}	Delete a specified device by device ID
GET	/v1.0/devices/{deviceId}/sub-devices	Query a list of devices under a gateway
GET	/v1.0/devices/factory-infos	Query the factory information of a device
PUT	/v1.0/devices/{device_id}	Modify a device name
GET	/v1.0/devices/{device_id}/status	Get the latest device status

Get device details

API description

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

API endpoint

GET /v1.0/devices/{device_id}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	The device ID.

Return parameter

Parameter name	Data type	Description
code	Integer	The response code. See Error codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
id	String	The device ID.
name	String	The device name.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
product_name	String	The product name.
sub	Boolean	Determines whether it is a 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 a specified home.
online	Boolean	The online status of a specified device.
status	Object<status>	The status of a specified device feature.
active_time	Long	The time when a specified device is activated, which is accurate to seconds.
biz_type	Long	The `biztype` of a specified application.
icon	String	The device icon. The prefix of China Data Center is `https://images.tuyacn.com`. If the relative path you get is `smart/product_icon/cz.png`, the actual icon URL is `https://images.tuyacn.com/smart/product_icon /cz.png`.
ip	String	The IP address of a specified device.

Description of status

Parameter name	Data type	Description
code	String	The code of a specified data point.
value	String	The value of a specified data point.
type	String	The type of a specified data point.

Sample request

GET /v1.0/devices/vdevo153490924188132

Sample SDK

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
DeviceVo deviceVo = client.getDeviceInfo(DEV_ID);
System.out.println("Get device details: ");
System.out.println(JSONObject.toJSONString(deviceVo));

Sample response

{
    "success": true,
    "result": {
        "active_time": 1589505938,
        "biz_type": 299009,
        "category": "qt",
        "create_time": 1560827137,
        "icon": "smart/icon/15402589135gknz23xajb_0.png",
        "id": "60613135b121cddc294****",
        "ip": "120.198.****.****",
        "local_key": "3a9b50126fe473****",
        "name": "Body fat scale",
        "online": true,
        "owner_id": "1070****",
        "product_id": "g0er6hSKgMqr****",
        "product_name": "Wifi scales_OEM",
        "status": [
            {
                "code": "weight",
                "value": 48900
            },
            {
                "code": "left_hand_r",
                "value": 0
            },
            {
                "code": "right_hand_r",
                "value": 0
            },
            {
                "code": "left_leg_r",
                "value": 0
            },
            {
                "code": "right_leg_r",
                "value": 0
            },
            {
                "code": "body_r",
                "value": 653
            },
            {
                "code": "battery_low",
                "value": false
            }
        ],
        "sub": false,
        "time_zone": "+08:00",
        "uid": "ay157896239864843g****",
        "update_time": 1589764585,
        "uuid": "60613135b23cddc294****"
    }
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Restore to factory defaults

API description

Restore the factory default settings of a specified device based on the device ID.

API endpoint

PUT /v1.0/devices/{device_id}/reset-factory

Request parameter

Parameter name	Data type	Required	Description
device_id	String	Yes	The device ID.

Sample request

PUT /v1.0/devices/6c362ac3c53fbd6f3e****/reset-factory

Return parameter

Parameter name	Data type	Description
code	Integer	The response code. See Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response

{
    "success": true,
    "t": 1550642917632,
    "result": true
}

Delete a specified device

API description

Delete a specified device by device ID.

API endpoint

DELETE /v1.0/devices/{device_id}

Request parameter

Parameter name	Data type	Required	Description
device_id	String	Yes	The device ID.

Sample request

DELETE /v1.0/devices/6c362ac3c53fbd6f3ew***

Return parameter

Parameter name	Data type	Description
code	Integer	The response code. See Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Query a list of devices under a gateway

API description

Query a list of devices under a specified gateway.

API endpoint

GET /v1.0/devices/{deviceId}/sub-devices

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	The device ID.

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	List<result>	The returned result.

Description of result

Parameter name	Parameter type	Description
id	String	The device ID.
name	String	The device name.
online	Boolean	The online status of a specified device.
owner_id	Long	The ID of a specified home.
category	Integer	Data type
product_id	Integer	The product ID.
active_time	String	The time when a specified device is activated.
update_time	String	The time when a specified device is modified.

Sample request

GET /v1.0/devices/vedeo16236124/sub-devices

Sample response

{
     "result": [
         {
             "active_time": 1586169374,
             "category": "sj",
             "id": "6c0746cfe887e21e8b****",
             "name": "Water leakage alarm",
             "online": true,
             "owner_id": "1059****",
             "product_id": "rzeSU2h9uoklx***",
             "update_time": 1586169379
         }
     ],
     "success": true,
     "t": 1586169580204
 }

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Query the factory information of a device

API description

Query the factory information of a specified device.

API endpoint

GET /v1.0/devices/factory-infos

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_ids	String	URL	Yes	The list of device IDs, separated with commas (,).

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	List<result>	The returned result.

Description of result

Parameter name	Parameter type	Description
id	String	The device ID.
uuid	String	The device name.
sn	String	The serial number of a specified device.
mac	String	The MAC address of a specified device.

Sample request

GET /v1.0/devices/factory-infos?device_ids=002008535ccf7f530***

Sample response

{
    "result": [
        {
            "id": "002008535ccf7f53****",
            "mac": "5c:cf:7f:53:**:**",
            "uuid": "002008535ccf7f53****"
        }
    ],
    "success": true,
    "t": 1585619435816
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Modify a device name

Modify a device name.

API endpoint

PUT /v1.0/devices/{device_id}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	The device ID.
name	String	BODY	Yes	Name

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	Boolean	The returned result.

Sample request

PUT /v1.0/devices/vedeo234567
{
    "name":""
}

Sample response

{
    "t":1234876331,
    "success":true,
    "result": true
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Add a user

API endpoint

POST /v1.0/devices/{device_id}/user

Request parameter

Parameter name	Parameter type	Required	Description
device_id	String	Yes	The device ID.
nick_name	String	Yes	The username.
sex	Integer	Yes	The gender. Valid values: `1`: male. `2`: female.
birthday	Long	No	The date of birth (day, month, year).
height	Integer	No	The height. Unit: centimeter.
weight	Integer	No	The weight. Unit: gram.
contact	String	No	The contact information.

Return parameter

Name	Data type	Description
t	Long	The returned time.
success	Boolean	Specifies whether the operation is successful.
result	String	The added user ID.

Sample request

POST /v1.0/devices/vedeo787322q/user

{
    "nick_name": "test",
    "sex": 1
}

Sample response

{
    "t":1564996327422,
    "success":true,
    "result": "5121231"
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Modify a user

API endpoint

PUT /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter name	Parameter type	Required	Description
device_id	String	Yes	The device ID.
user_id	String	Yes	The added user ID.
nick_name	String	Yes	The username.
sex	Integer	Yes	The gender. Valid values: `1`: male. `2`: female.
birthday	Long	No	The date of birth (day, month, year).
height	Integer	No	The height. Unit: centimeter.
weight	Integer	No	The weight. Unit: gram.

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	Object	The returned result.

Sample request

PUT /v1.0/devices/vedeo16236124/users/12445765

{
    "nick_name": "",
    "sex": 1,
    "birthday": 1544996327422,
    "height": 178,
    "weight": 160
}

Sample response

{
    "t":1564996327422,
    "success":true,
    "result": true
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Delete a user

API endpoint

DELETE /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter name	Parameter type	Required	Description
device_id	String	Yes	The device ID.
user_id	String	Yes	The user ID.

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	Boolean	The returned result.

Sample request

DELETE /v1.0/devices/vedeo16236124/users/5232342

Sample response

{
    "t":1564996327422,
    "success":true,
    "result": true
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Query user information

API endpoint

GET /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter name	Parameter type	Required	Description
device_id	String	Yes	The device ID.
user_id	String	Yes	The user ID.

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	Object	The returned result.

Description of result

Parameter name	Parameter type	Description
device_id	String	The device ID.
nick_name	String	The username.
sex	Integer	The gender. Valid values: `1`: male. `2`: female.
birthday	Long	The date of birth (day, month, year).
height	Integer	The height. Unit: centimeter.
weight	Integer	The weight. Unit: gram.
contact	String	The contact information.

Sample request

GET /v1.0/devices/vedeo16236124/users/5232342

Sample response

{
    "t":1564996327422,
    "success":true,
    "result": 
      {
        "device_id": "vedeo1623****",
        "nick_name": "",
        "sex": 1,
        "birthday": 1544996327422,
        "height": 178,
        "weight": 160,
        "contact": ""
      }
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Query user information by device ID

API endpoint

GET /v1.0/devices/{device_id}/users

Request parameter

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

Return parameter

Name	Data type	Description
t	Long	The timestamp.
success	Boolean	Specifies whether the operation is successful.
result	List<result>	The returned result.

Description of result

Parameter name	Parameter type	Description
device_id	String	The device ID.
nick_name	String	The username.
sex	Integer	The gender. Valid values: `1`: male. `2`: female.
birthday	Long	The date of birth (day, month, year).
height	Integer	The height. Unit: centimeter.
weight	Integer	The weight. Unit: gram.
contact	String	The contact information.

Sample request

GET /v1.0/devices/vedeo16236124/users

Sample response

{
    "t":1564996327422,
    "success":true,
    "result": [
      {
        "device_id": "vedeo1623****",
        "nick_name": "",
        "sex": 1,
        "birthday": 1544996327422,
        "height": 178,
        "weight": 160,
        "contact": ""
      }
    ]
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Get the latest device status

API description

Get the latest device status by device ID.

API endpoint

GET /v1.0/devices/{device_id}/status

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	The device ID.

Return parameter

Parameter name	Data type	Description
code	Integer	The response code. See Error code.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample request

GET /v1.0/devices/{device_id}/status

Sample SDK

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<Status> deviceStatus= client.getDeviceStatus(DEV_ID);
System.out.println("Get device status: ");
System.out.println(JSONObject.toJSONString(deviceStatus));

Sample response

{
      "success": true,
      "t": 1545447665981,
      "result": [
          {
              "code": "switch_led",
              "value": true
          },
          {
              "code": "work_mode",
              "value": "scene_2"
          },
          {
              "code": "bright_value",
              "value": 25
          },
          {
              "code": "temp_value",
              "value": 0
          },
          {
              "code": "colour_data",
              "value": "{\"h\":37.0,\"s\":255.0,\"v\":189.0}"
          },
          {
              "code": "scene_data",
              "value": ""
          },
          {
              "code": "flash_scene_1",
              "value": ""
          },
          {
              "code": "flash_scene_2",
              "value": ""
          },
          {
              "code": "flash_scene_3",
              "value": ""
          },
          {
              "code": "flash_scene_4",
              "value": "{\"bright\":255,\"frequency\":80,\"hsv\":[{\"h\":0.0,\"s\":255.0,\"v\":255.0},{\"h\":120.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":300.0,\"s\":255.0,\"v\":255.0},{\"h\":240.0,\"s\":255.0,\"v\":255.0},{\"h\":0.0,\"s\":255.0,\"v\":255.0}],\"temperature\":255}"
          }
      ]
  }

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.

Prev DocDevice Control

Next DocSmart Home Multiple Device Setting