Cloud Services API ReferenceSmart HomeSmart Home Basic ServiceDevice Management

Device Management

Last Updated on : 2023-11-29 09:25:20download

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/users/{uid}/devices	Get a list of devices under a specified user
GET	/v1.0/devices	Get a list of devices
PUT	/v1.0/devices/{device_id}/functions/{function_code}	Modify the name of a data point
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
POST	/v1.0/devices/{device_id}/user	Add a device user
DELETE	/v1.0/devices/{device_id}/users/{user_id}	Delete a specified user
PUT	/v1.0/devices/{device_id}/users/{user_id}	Modify a specified user
GET	/v1.0/devices/{device_id}/users/{user_id}	Query the information about a specified user
GET	/v1.0/devices/{device_id}/users	Query a list of users associated with a device
PUT	/v1.0/devices/{device_id}/multiple-name	Modify names of a multi-outlet device
GET	/v1.0/devices/{device_id}/multiple-names	Get names of a multi-outlet device

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.

Get a list of devices under a specified user

API description

Query the list of devices available to a specified user, including device attributes and the latest status.

API endpoint

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

Request parameter

Parameter name	Data type	Parameter type	Required	Description
uid	String	URI	Yes	Tuya user ID.
from	String	query	No	The source. Valid values: `home`: Query the devices in the rooms of the current user. `sharing`: Query the shared devices that the current user has received.
page_no	Integer	query	No	The current page number. `1` means the first page.
page_size	Integer	query	No	The number of entries returned on each page.

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.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
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 the device owner.
online	Boolean	The online status of a specified device.
name	String	The device name.
ip	String	The IP address.
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 is last updated.
active_time	Long	The time when the device is last paired.
status	List<status>	The status of a specified device feature.

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.

Sample request

GET /v1.0/users/ay15*******/devices
GET /v1.0/users/ay15*******/devices?page_no=1&page_size=50

Sample SDK

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<DeviceVo> deviceFunctions = client.getUserDevices(UID);
System.out.println("Get a list of devices under a specified user: ");
System.out.println(JSONObject.toJSONString(deviceFunctions));

Sample response

{
    "result":[
        {
            "sub":false,
            "create_time":1540691155,
            "local_key":"11a53bdd67e4****",
            "owner_id":"357****",
            "ip":"**.62.43.**",
            "biz_type":293964,
            "icon":"smart/product_icon/cz.png",
            "time_zone":"+08:00",
            "uuid":"27511006b4e62d4b****",
            "product_name":"Wi-Fi Smart Metering Socket",
            "active_time":1548584422,
            "uid":"ay1548569152777Q****",
            "update_time":1548584559,
            "product_id":"EvolhYPyZNWYP***",
            "name":"xxx test",
            "online":true,
            "id":"27511006b4e62d4b****",
            "category":"cz",
            "status":[
                {
                    "code":"cur_power",
                    "value": 0
                },
                {
                    "code":"cur_voltage",
                    "value": 2196
                },
                {
                    "code":"switch",
                    "value": false
                },
                {
                    "code":"countdown_1",
                    "value": 0
                },
                {
                    "code":"cur_current",
                    "value": 0
                }
            ]
        }
    ],
    "t":1564996327422,
    "success":true
}

Error codes

The following table lists common error codes for 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.

Get a list of devices

API description

Query a list of devices based on one of the following parameters: application, product, or device ID. You can get the relevant device data if either of the following resources has access to the target device:

Application dimension
A device buyer can get a list of devices associated with an application. The application can be an OEM app created on the Tuya IoT Development Platform or self-developed based on Tuya’s client SDK. The device buyer binds the application with the devices, and thus gets the device data.
Product dimension
A device manufacturer can get a list of devices associated with a product. A manufacturer creates a product on the Tuya IoT Development Platform, produces devices on this basis (make sure devices are connected to the cloud), and then gets or controls the data of the devices.

Cloud APIs are used to query the activated real devices and virtual devices. It is not completely consistent with the query strategy of device management on the Tuya IoT Development Platform. Device management on the platform only enables you to query the real devices that are activated or removed. The maximum time span between the start and end times of a query is 30 days. We recommend that you shorten the query period based on the daily increase of the devices, helping to speed up the query.

API endpoint

GET /v1.0/devices

Request parameter

Parameter name	Data type	Parameter type	Required	Description
page_no	Integer	query	Yes	The current page number.
page_size	Integer	query	Yes	The number of entries returned on each page.
schema	String	query	No	The schema of a specified application.
product_id	String	query	No	The product ID.
device_ids	String	query	No	The list of device IDs.
start_time	String	query	No	The 10-digit timestamp of the start time for a query.
end_time	String	query	No	The 10-digit timestamp of the end time for a query.

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
total	Long	The total number of entries.
devices	List<devices>	The list of returned devices.
last_id	String	The last query ID of a specified device.

Description of devices

Parameter name	Data 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	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 the device owner.
online	Boolean	The online status of a specified device.
name	String	The device name.
ip	String	The IP address.
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 is last updated.
active_time	Long	The time when the device is last paired.
status	List<status>	The status of a specified device feature.

Description of status

Parameter name	Data type	Description
code	String	The code of specified device status.
value	Object	The value of specified device status. For more information about the `value`, see the standard status set. The `value` might be Boolean, integer, or string. The actual device shall prevail.

When the total amount of data is too large in a query, we recommend you use the combination of page_size + last_id instead of page_size + page_no. For more information, see the example.

Sample request

GET /v1.0/devices?schema=testApp
GET /v1.0/devices?product_id=*******
GET /v1.0/devices?device_ids=vdevo15****88132,vdevo1***188132
GET /v1.0/devices?last_id=1584939489&page_size=20

Sample SDK

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
BatchDevices batchDevices = client.getDeviceListInfo(devIds);
System.out.println("Get device details in bulk: ");
System.out.println(JSONObject.toJSONString(batchDevices));

Sample response

{
    "result": {
        "devices": [
            {
                "active_time": 1584063323,
                "biz_type": 310002,
                "category": "znyxss",
                "create_time": 1575017570,
                "icon": "smart/program_category_icon/znyxss.png",
                "id": "747b2165d9449964****",
                "ip": "58.251.**.****",
                "local_key": "11d7f7286caa****",
                "model": "SS190",
                "name": "Wi-Fi smart speaker SS190",
                "online": false,
                "owner_id": "1160****",
                "product_id": "i9vkz***",
                "product_name": "Wi-Fi smart speaker SS190",
                "status": [
                    {
                        "code": "smartspeaker_vol",
                        "value": 26
                    },
                    {
                        "code": "smartspeaker_mic",
                        "value": true
                    },
                    {
                        "code": "smartspeaker_play",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_wm_switch",
                        "value": "btm"
                    },
                    {
                        "code": "smartspeaker_bt_switch",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_pre",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_next",
                        "value": false
                    },
                    {
                        "code": "smartspeaker_play_mode",
                        "value": "random"
                    },
                    {
                        "code": "smartspeaker_alarm_clock",
                        "value": ""
                    },
                    {
                        "code": "smartspeaker_alert",
                        "value": ""
                    },
                    {
                        "code": "ir_send",
                        "value": "{\"control\":\"study_exit\"}"
                    },
                    {
                        "code": "ir_study_code",
                        "value": ""
                    }
                ],
                "sub": false,
                "time_zone": "+08:00",
                "uid": "ay156531946658X****",
                "update_time": 1584939489,
                "uuid": "12****"
            }
        ],
        "last_id": "158493****",
        "total": 1
    },
    "success": true,
    "t": 1586741851210
}

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.

Modify the name of a data point

API description

Modify the name of a data point for a sub-device.

API endpoint

PUT /v1.0/devices/{device_id}/functions/{function_code}

Request parameter

Parameter name	Data type	Parameter location	Required	Description
device_id	String	URI	Yes	The device ID.
function_code	String	URI	Yes	The code of a specified data point.
name	String	Body	Yes	The name of a specified data point.

Sample request

PUT /v1.0/devices/vdevo156083035305868/functions/switch_1
{
  "name":"lalal"
}

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	Object	The returned result.
t	Long	The timestamp.

Sample response

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

Query device logs

API description

Query the operation logs of a specified device according to the specified criteria.

API endpoint

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

Request parameter

Parameter name	Data type	Parameter location	Required	Description
device_id	String	URI	Yes	The device ID.
type	String	URL	Yes	The supported types of logs. You can query multiple event types, separated with commas (,). This parameter value is required. For more information, see the Description of event types.
start_time	Long	URL	Yes	The 13-digit timestamp of the start time for a query. If the value is `0` or empty, the start time will be automatically set to the timestamp 7 days ago. The `start_time` shall be set to a larger value, to avoid timeout resulting from querying too much data at one time.
end_time	Long	URL	Yes	The 13-digit timestamp of the end time for a query.
codes	String	URL	No	The codes of data points supported by the device. You can query multiple data points, separated with commas (,). This parameter value is empty by default.
start_row_key	String	URL	No	Query the row key of HBase. As a parameter of the free edition, the default value is empty.
last_row_key	String	URL	No	The row key of the last entry on each page. This is a required parameter for the paid edition. The default value is empty, which means the first page.
last_event_time	Long	URL	No	The event occurrence time of the last entry on each page. This is a required parameter for the paid edition. The default value is empty, which means the first page.
size	int	URL	No	The number of logs allowed to be returned. Default value: `20`.
query_type	Integer	URL	No	The query type. Valid values: `1`: free edition `2`: paid edition

Sample request

Sample request of the free edition

{{url}}/v1.0/devices/78304402ecfabc1fd5b2/logs?start_row_key=&type=1,2&start_time=0&end_time=1545898159935&size=20

Sample request of the paid edition

GET /v1.0/devices/03200026dc4f221b6d6d/logs?type=7&start_time=0&end_time=1545898159935&size=20&query_type=2&last_row_key=650823455f68a9cbafce08700557_9223370475075511414_1&last_event_time=1561779264393

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	Object<result>	The returned result.
t	Long	The timestamp.

Description of result

Parameter name	Data type	Description
logs	Object<logs>	The log message body.
has_next	Boolean	Specifies whether to return the next page.
device_id	String	The device ID.
current_row_key	String	The current row key of Hbase. This is a parameter of the free edition.
next_row_key	String	The next HBase row key that meets the query criteria. This is a parameter of the free edition. Note: If null is returned, it means that there is no next log that meets the query criteria.
count	Long	The total number of logs that meet the query criteria. This is a parameter of the paid edition.

Description of logs

Parameter name	Data type	Description
code	String	The code of a specified data point.
value	String	The value of a specified data point.
event_time	String	The timestamp when an event occurs.
event_from	String	The source that triggers the event. For more information, see the Description of event sources.
event_id	String	The event type. For more information, see the Description of event types.
status	String	The data is valid and not deleted. Default value: `1`.
row	String	The current row key of Hbase. This is a parameter of the paid edition.

Sample response

Sample response on success

Free edition

{
"success": true,
"t": 1561344464370,
"result": {
    "logs": [
        {
            "code": "switch_1",
            "value": "false",
            "event_time": 1560872567955,
            "event_from": "1",
            "event_id": 7
        },
        {
            "code": "switch_1",
            "value": "false",
            "event_time": 1560783276382,
            "event_from": "1",
            "event_id": 7
        }
    ],
    "device_id": "75500780ecfabc9a****",
    "has_next": true,
    "current_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc1OTgyMjA3ODUyXzdfMQ==",
    "next_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc2MDcxNDk5OTM0XzdfMQ=="
	}
}

Paid edition

{
"success":true,
    "t":1561344464370,
    "result":{
        "count":32,
        "device_id":"75500780ecfabc9a****",
        "has_next":true,
        "logs":[
            {
                "event_id":1,
                "event_time":1562031576431,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823199376_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1562031394665,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823381142_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1562031277824,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474823497983_1",
                "status":"1"
            },
            {
                "event_id":1,
                "event_time":1561935500636,
                "event_from":"1",
                "row":"650823455f68a9cbafce08700557_9223370474919275171_1",
                "status":"1"
            }
        ]
    }
}

Sample response on failure

	{
    "success": false,
    "code": 2009,
    "msg": "not support this device",
    "t": 1561348644346
	}

Description of event sources

code	Description
1	The device.
2	Commands from the client.
3	A third-party platform.
4	Commands from the cloud.
5	Device removed from the mobile app.
6	Factory reset via the mobile app.
7	Update notification of the app.
8	Force update of the device.
9	Force update of the app.
10	Manual check for app updates.
11	Device removed from the Tuya IoT Development Platform.
12	Device removed by the developer.
13	Device removed from the client.
16	Energy-saving miniapp.
-1	Unknown.

Description of event types

code	Description
1	A device goes online.
2	A device goes offline.
3	A device is activated.
4	A device is reset.
5	An instruction is sent from the cloud to the device.
6	The firmware is updated.
7	A data point is reported from the device to the cloud.
8	Device semaphore.
9	A device is restarted.
10	Scheduling information.

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.

Modify names of a multi-outlet device

Modify the names of a multi-outlet device, such as a multi-outlet power strip.

API endpoint

PUT /v1.0/devices/{device_id}/multiple-name

Request parameter

Parameter name	Data type	Parameter type	Description	Required
device_id	String	URI	Yes	The device ID.
identifier	String	BODY	Yes	The identifier.
name	String	BODY	Yes	The 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/multiple-name
{
    "identifier":"",
    "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.

Get names of a multi-outlet device

Get names of a multi-outlet device.

API endpoint

GET /v1.0/devices/{device_id}/multiple-names

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	The returned result.

Description of result

Name	Data type	Description
identifier	String	The identifier.
name	String	Name

Sample request

GET /v1.0/devices/vedeo234567/multiple-names

Sample response

{
    "t":1234876331,
    "success":true,
    "result": [
    {
        "identifier":"",
        "name":""
    }]
}

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 Data Profile