Last Updated on : 2023-12-07 03:33:44download
This topic describes the related APIs of whole house management.
Request method | API | Description |
---|---|---|
POST | /v1.0/home/create-home | Add a home |
PUT | /v1.0/homes/{home_id} | Modify a home |
DELETE | /v1.0/homes/{home_id} | Delete a home |
GET | /v1.0/homes/{home_id} | Query a home |
GET | /v1.0/homes/{home_id}/devices | Query the list of devices in a home |
POST | /v1.0/homes/{home_id}/members | Add a home member |
PUT | /v1.0/homes/{home_id}/members/{uid} | Set permissions for members |
DELETE | /v1.0/homes/{home_id}/members/{uid} | Delete a home member |
GET | /v1.0/homes/{home_id}/members | Query home members |
GET | /v1.0/users/{uid}/homes | Query the list of home that the user lives in |
GET | /v1.0/homes/{home_id}/rooms/{room_id}/devices | Query the devices in the rooms of a home |
POST | /v1.0/homes/{home_id}/rooms/{room_id}/devices | Add a device in a room of a home |
PUT | /v1.0/homes/{home_id}/rooms/{room_id}/devices | Modify a device in a room of a home |
DELETE | /v1.0/homes/{home_id}/rooms/{room_id}/devices | Delete a device in a room of a home |
Add a new home and rooms for the user.
Note: You can add a home without a room.
POST /v1.0/home/create-home
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
uid | String | URI | Yes | Tuya user |
home | Object | BODY | Yes | Home |
rooms | List | BODY | No | Room |
Description of home
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
name | String | BODY | Yes | Home name |
geo_name | String | BODY | No | Geographical location of a home |
lon | Double | BODY | No | Longitude |
lat | Double | BODY | No | Latitude |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Long | Home ID, which refers to home_id . |
POST /v1.0/home/create-home
{
"uid":"ay1528964101460qLVPu",
"home":{
"geo_name":"Hangzhou, Wealth Center",
"name":"My home",
"lat":30.16**,
"lon":120.5**
},
"rooms":[
"Kitchen",
"Bathroom"
]
}
N/A
{ "success": true, "t": 1540615024283, "result": 3182004 }
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Modify the basic information of a home.
PUT /v1.0/homes/{home_id}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
name | String | BODY | No | Home name |
geo_name | String | BODY | No | Geographical location of a home |
lon | Double | BODY | No | Longitude |
lat | Double | BODY | No | Dimension |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Boolean | Return true if the modification succeeds. |
PUT /v1.0/homes/3196002
{
"geo_name":"Hangzhou, Tuya Smart",
"name":"My home",
"lat":30.16**,
"lon":120.5**
}
N/A
{
"success": true,
"t": 1540616318050,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Delete a home according to the home ID.
DELETE /v1.0/homes/{home_id}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Boolean | Return true if the deletion succeeds. |
DELETE /v1.0/homes/3196006
N/A
{
"success": true,
"t": 1540958118207,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query a home by home ID.
GET /v1.0/homes/{home_id}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object<result> | Home object |
Description of result
Parameter name | Data type | Description |
---|---|---|
home_id | Long | Scene ID |
name | String | Home name |
geo_name | String | Geographical location of a home |
lon | Double | Longitude |
lat | Double | Latitude |
GET /v1.0/homes/3182004
N/A
{
"success": true,
"t": 1540955256215,
"result": {
"name": "Someone's home",
"lon": 120.5**,
"lat": 30.16**,
"home_id": 318****,
"geo_name": "Hangzhou, Tuya Smart"
}
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query the device list in a home by home ID.
GET /v1.0/homes/{home_id}/devices
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object<result> | Return the list of device details. |
Description of result
Parameter name | Data type | Description |
---|---|---|
id | String | Device code |
uid | String | User ID |
local_key | String | Key |
category | String | Product category |
product_id | String | Product ID |
sub | Boolean | Determine whether it is a sub-device
|
uuid | String | The unique identifier of a device |
owner_id | String | Device owner ID |
online | Boolean | Online status of the device |
ip | String | Device IP |
name | String | Device name |
time_zone | String | Time zone of the device |
status | Object<status> | Functional status of the device |
Description of status
Parameter name | Data type | Description |
---|---|---|
code | String | Code of the data point |
value | String | Data point value |
GET /v1.0/homes/3196002/devices
N/A
{
"success":true,
"t":1541509099860,
"result":[
{
"uuid":"vdevo15350082749****",
"uid":"ay1528964101460q****",
"name":"Someone's socket",
"ip":null,
"sub":false,
"status":[
{
"code":"switch",
"value": true
},
{
"code":"countdown_1",
"value": 0
}
],
"category":"cz",
"online":true,
"id":"vdevo15350082749****",
"time_zone":"+08:00",
"local_key":"47a5a361719f****",
"owner_id":"242****",
"product_id":"T62ZA4lyVXF****"
},
{
"uuid":"vdevo15401776953****",
"uid":"ay1528964101460q****",
"name":"Public version curtain",
"ip":null,
"sub":false,
"status":[
{
"code":"control",
"value":"open"
},
{
"code":"percent_control",
"value": 0
},
{
"code":"percent_state",
"value": 0
},
{
"code":"mode",
"value":"morning"
},
{
"code":"control_back",
"value": false
},
{
"code":"auto_power",
"value": false
},
{
"code":"work_state",
"value":"opening"
},
{
"code":"countdown",
"value": 2
},
{
"code":"countdown_left",
"value": 0
},
{
"code":"fault",
"value": 0
},
{
"code":"time_total",
"value": 0
}
],
"category":"qt",
"online":true,
"id":"vdevo15401776953****",
"time_zone":"+08:00",
"local_key":"75bc0238e71e****",
"owner_id":"242****",
"product_id":"9ysAXds4ohDA****"
}
]
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Request method | API | Description |
---|---|---|
POST | /v1.0/homes/{home_id}/room | Add a room |
PUT | /v1.0/homes/{home_id}/rooms/{room_id} | Modify a room |
DELETE | /v1.0/homes/{home_id}/rooms/{room_id} | Delete a room |
GET | /v1.0/homes/{home_id}/rooms | Query the information of a home and rooms |
Add a room according to the home ID
POST /v1.0/homes/{home_id}/room
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
name | String | BODY | Yes | Room name |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Long | Room ID, which refers to room_id . |
POST /v1.0/homes/3182004/room
{
"name":"Kitchen 3"
}
N/A
{
"success": true,
"t": 1540958436848,
"result": 1408001
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Modify a room according to the home ID and room ID
PUT /v1.0/homes/{home_id}/rooms/{room_id}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
name | String | BODY | Yes | Room name |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object | Return true if the modification succeeds. |
PUT /v1.0/homes/3196002/rooms/1408001
{
"name":"Kitchen 5"
}
N/A
{
"success": true,
"t": 1540635347168,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Delete a room according to the home ID and room ID.
DELETE /v1.0/homes/{home_id}/rooms/{room_id}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Boolean | Return true if the deletion succeeds. |
DELETE /v1.0/homes/3196002/rooms/1408001
N/A
{
"success": true,
"t": 1540635347168,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query the information of a home and rooms by home ID.
GET /v1.0/homes/{home_id}/rooms
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | String | URI | Yes | Home ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object<result> | The returned result. |
Description of result
Parameter name | Data type | Description |
---|---|---|
home_id | String | Scene ID |
name | String | Home name |
geo_name | String | Geographical location of a home |
lon | Double | Longitude |
lat | Double | Latitude |
rooms | List<rooms> | Room list |
Description of rooms
Parameter name | Category | Description |
---|---|---|
room_id | Long | Room ID |
name | String | Room name |
GET /v1.0/homes/3196002/rooms
N/A
{
"success":true,
"t":1540869200562,
"result":{
"home_id":3196002,
"name":"Someone's home",
"lon":120.5**,
"lat":30.16**,
"geo_name":"Hangzhou, Wealth Center",
"rooms":[
{
"room_id":139****,
"name":"Kitchen"
},
{
"room_id":139****,
"name":"Bathroom"
}
]
}
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Add a member to a specified home.
POST /v1.0/homes/{home_id}/members
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | String | URI | Yes | Home ID |
app_schema | String | BODY | Yes | Account identifier |
member | Object | BODY | Yes | Member object |
Description of member
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
country_code | String | URI | Yes | Country code |
member_account | String | BODY | Yes | Member account |
admin | Boolean | BODY | Yes | Determine whether it is an administrator or not |
name | String | BODY | Yes | Member name |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object | Return true if the adding succeeds. |
POST /v1.0/homes/2422120/members
{
"app_schema":"test",
"member":{
"country_code":"86",
"member_account":"1565815****",
"admin":false,
"name":"Someone"
}
}
N/A
{
"success": true,
"t": 1540799657137,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Set role permissions of administrator and non-administrator for a home member, and modify a member’s name.
PUT /v1.0/homes/{home_id}/members/{uid}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | String | URI | Yes | Home ID |
uid | String | URI | Yes | Tuya user ID |
admin | Boolean | BODY | Yes | Home administrator identifier.
|
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object | Return true if the modification succeeds. |
PUT /v1.0/homes/3196002/members/ay15309353754999xY2T
{
"admin":false
}
TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<DeviceVo> deviceFunctions = client.getUserDevices(UID);
System.out.println("Get the device list of the user: ");
System.out.println(JSONObject.toJSONString(deviceFunctions));
{
"success": true,
"t": 1540807132951,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Delete a member of the specified home.
DELETE /v1.0/homes/{home_id}/members/{uid}
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
uid | String | URI | Yes | Tuya user ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object | Return true if the deletion succeeds. |
DELETE /v1.0/homes/3196002/members/ay15309353754999xY2T
N/A
{
"success": true,
"t": 1540967859608,
"result": true
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query the list of home members
GET /v1.0/homes/{home_id}/members
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | String | URI | Yes | Home ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | Object<result> | The list of home members. |
Description of result
Parameter name | Category | Description |
---|---|---|
uid | String | Tuya user ID |
admin | Boolean | Determine whether the user is a home administrator or not.
|
mame | String | Username of the home member |
country_code | String | Country code of the home member |
member_account | String | Account of the home member |
GET /v1.0/homes/2422120/members
N/A
{
"success":true,
"t":1540799929837,
"result":[
{
"country_code":"86",
"member_account":"18******176",
"uid":"ay1528964101460q****",
"admin":true,
"name":"Someone1"
},
{
"country_code":"86",
"member_account":"15******196",
"uid":"ay15309353754999****",
"admin":false,
"name":"Someone2"
}
]
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query the list of home that the user lives in by uid
.
GET /v1.0/users/{uid}/homes
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
uid | String | URI | Yes | Tuya user ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
result | List | The list of home details. |
Description of result
Parameter name | Data type | Description |
---|---|---|
home_id | Long | Home ID |
name | String | Home name |
geo_name | String | Geographical location of a home |
lon | Double | Longitude |
lat | Double | Latitude |
GET /v1.0/users/ay1528964101460qLVPu/homes
N/A
{
"success":true,
"t":1541508940996,
"result":[
{
"name":"Somewhere",
"lon":120.10****,
"lat":30.27****,
"home_id":242****,
"geo_name":"Example district, example street"
},
{
"name":"Someone's home",
"lon":120.09****,
"lat":30.30****,
"home_id":317****,
"geo_name":"Some city, some place"
},
{
"name":"Example home",
"lon":120.5****,
"lat":30.16****,
"home_id":319****,
"geo_name":"Hangzhou, Tuya Smart"
}
]
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error |
1106 | Illegal permission |
Query the device in the room of a home
GET /v1.0/homes/{home_id}/rooms/{room_id}/devices
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
t | Long | Return a 13-bit timestamp. |
result | List | The returned result. |
Request example
GET /v1.0/homes/25674317/rooms/18002322/devices
Response example
{
"result": [
{
"active_time": 1601276997,
"biz_type": 116030,
"category": "dj",
"create_time": 1601276997,
"icon": "smart/icon/ay1536722357072RkR2q/3ef200ae4de60ec651689208ade1dbaf.png",
"id": "vdevo16012769974****",
"ip": "",
"local_key": "023b0565cafb****",
"name": "Wi-Fi test 1.2-vdevo",
"online": true,
"owner_id": "2567****",
"product_id": "afctjpmhjvxr****",
"product_name": "Wi-Fi test 1.2",
"status": [
{
"code": "switch_led",
"value": "false"
},
{
"code": "work_mode",
"value": "scene"
},
{
"code": "bright_value_v2",
"value": "10"
},
{
"code": "temp_value_v2",
"value": "0"
},
{
"code": "colour_data_v2",
"value": ""
},
{
"code": "scene_data_v2",
"value": "{\"scene_num\":1,\"scene_units\":[{\"bright\":200,\"h\":0,\"s\":0,\"temperature\":0,\"unit_change_mode\":\"static\",\"unit_gradient_duration\":13,\"unit_switch_duration\":14,\"v\":0}]}"
},
{
"code": "countdown_1",
"value": "0"
},
{
"code": "control_data",
"value": ""
}
],
"sub": false,
"time_zone": "",
"uid": "ay1555492511130R****",
"update_time": 1601276997,
"uuid": "vdevo16012769974****"
}
],
"success": true,
"t": 1603804495501
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error. Contact the administrator |
Add a device in the room of a home
POST /v1.0/homes/{home_id}/rooms/{room_id}/devices
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
device_ids | List | BODY | Yes | The newly added device ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
t | Long | Return a 13-bit timestamp. |
result | Boolean | The returned result. |
POST /v1.0/homes/123111/rooms/74332323/devices
{
"device_ids":["ve23u9****","ve23u92****"]
}
{
"result":true,
"success": true,
"t": 1587551002533
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error. Contact the administrator |
Modify a device in a room of a home
PUT /v1.0/homes/{home_id}/rooms/{room_id}/devices
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
device_ids | List | BODY | Yes | The last device ID reserved in the room |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
t | Long | Return a 13-bit timestamp. |
result | Boolean | The returned result. |
PUT /v1.0/homes/123111/rooms/74332323/devices
{
"device_ids":["ve23u9****","ve23u92****"]
}
{
"result":true,
"success": true,
"t": 1587551002533
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error. Contact the administrator |
Delete a device in a room of the home
DELETE /v1.0/homes/{home_id}/rooms/{room_id}/devices
Parameter name | Data type | Parameter type | Required | Description |
---|---|---|---|---|
home_id | Long | URI | Yes | Home ID |
room_id | Long | URI | Yes | Room ID |
device_ids | List | BODY | Yes | The deleted device ID |
Parameter name | Data type | Description |
---|---|---|
code | Integer | Response code. See Error code. |
success | Boolean | Determine whether the request succeeded or not.
|
msg | String | The message returned if the request fails. It will return null if the request succeeds. |
t | Long | Return a 13-bit timestamp. |
result | Boolean | The returned result. |
DELETE /v1.0/homes/123111/rooms/74332323/devices
{
"device_ids":["ve23u9****","ve23u92****"]
}
{
"result":true,
"success": true,
"t": 1587551002533
}
The following are common service exceptions for this interface. For more exception errors, see Error Code.
Error code | Description |
---|---|
500 | System error. Contact the administrator |
Is this page helpful?
YesFeedbackIs this page helpful?
YesFeedback