Smart Home Management

Last Updated on : 2023-12-07 03:33:44download

This topic describes the related APIs of whole house management.

API list

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 home

API description

Add a new home and rooms for the user.

Note: You can add a home without a room.

API address

POST /v1.0/home/create-home

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

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"
   ]
}

SDK example

N/A

Return example

{ "success": true, "t": 1540615024283, "result": 3182004 }

Error code

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 home

API description

Modify the basic information of a home.

API address

PUT /v1.0/homes/{home_id}

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

PUT /v1.0/homes/3196002
{
 "geo_name":"Hangzhou, Tuya Smart",
 "name":"My home",
 "lat":30.16**,
 "lon":120.5**
}

SDK example

N/A

Return example

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

Error code

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

API description

Delete a home according to the home ID.

API address

DELETE /v1.0/homes/{home_id}

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

DELETE /v1.0/homes/3196006

SDK example

N/A

Return example

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

Error code

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

API description

Query a home by home ID.

API address

GET /v1.0/homes/{home_id}

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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

Request example

GET /v1.0/homes/3182004

SDK example

N/A

Return example

{ "success": true, "t": 1540955256215, "result": { "name": "Someone's home", "lon": 120.5**, "lat": 30.16**, "home_id": 318****, "geo_name": "Hangzhou, Tuya Smart" } }

Error code

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 device details in a home

API description

Query the device list in a home by home ID.

API address

GET /v1.0/homes/{home_id}/devices

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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
  • true: yes
  • false: No
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

Request example

GET /v1.0/homes/3196002/devices

SDK example

N/A

Return example

{ "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****" } ] }

Error code

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

Room management

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

API description

Add a room according to the home ID

API address

POST /v1.0/homes/{home_id}/room

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID
name String BODY Yes Room name

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

POST /v1.0/homes/3182004/room
{
 "name":"Kitchen 3"
}

SDK example

N/A

Return example

{ "success": true, "t": 1540958436848, "result": 1408001 }

Error code

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

API description

Modify a room according to the home ID and room ID

API address

PUT /v1.0/homes/{home_id}/rooms/{room_id}

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

PUT /v1.0/homes/3196002/rooms/1408001
{
 "name":"Kitchen 5"
}

SDK example

N/A

Return example

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

Error code

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

API description

Delete a room according to the home ID and room ID.

API address

DELETE /v1.0/homes/{home_id}/rooms/{room_id}

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID
room_id Long URI Yes Room ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

DELETE /v1.0/homes/3196002/rooms/1408001

SDK example

N/A

Return example

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

Error code

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

API description

Query the information of a home and rooms by home ID.

API address

GET /v1.0/homes/{home_id}/rooms

Request parameter

Parameter name Data type Parameter type Required Description
home_id String URI Yes Home ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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

Request example

GET /v1.0/homes/3196002/rooms

SDK example

N/A

Return example

{ "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" } ] } }

Error code

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 home member

API description

Add a member to a specified home.

API address

POST /v1.0/homes/{home_id}/members

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

POST /v1.0/homes/2422120/members
{
   "app_schema":"test",
   "member":{
       "country_code":"86",
       "member_account":"1565815****",
       "admin":false,
       "name":"Someone"
   }
}

SDK example

N/A

Return example

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

Error code

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 permissions for members

API description

Set role permissions of administrator and non-administrator for a home member, and modify a member’s name.

API address

PUT /v1.0/homes/{home_id}/members/{uid}

Request parameter

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.
  • true: administrator
  • false: non-administrator

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

PUT /v1.0/homes/3196002/members/ay15309353754999xY2T
{
 "admin":false
}

SDK example

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));

Return example

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

Error code

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 member

API description

Delete a member of the specified home.

API address

DELETE /v1.0/homes/{home_id}/members/{uid}

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID
uid String URI Yes Tuya user ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

DELETE /v1.0/homes/3196002/members/ay15309353754999xY2T

SDK example

N/A

Return example

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

Error code

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 home members

API description

Query the list of home members

API address

GET /v1.0/homes/{home_id}/members

Request parameter

Parameter name Data type Parameter type Required Description
home_id String URI Yes Home ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.
  • true: yes
  • false: no
mame String Username of the home member
country_code String Country code of the home member
member_account String Account of the home member

Request example

GET /v1.0/homes/2422120/members

SDK example

N/A

Return example

{ "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" } ] }

Error code

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

API description

Query the list of home that the user lives in by uid .

API address

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

Request parameter

Parameter name Data type Parameter type Required Description
uid String URI Yes Tuya user ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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

Request example

GET /v1.0/users/ay1528964101460qLVPu/homes

SDK example

N/A

Return example

{ "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" } ] }

Error code

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

Function description

Query the device in the room of a home

API address

GET /v1.0/homes/{home_id}/rooms/{room_id}/devices

Request parameter

Parameter name Data type Parameter type Required Description
home_id Long URI Yes Home ID
room_id Long URI Yes Room ID

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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 }

Error code

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 a room of a home

API description

Add a device in the room of a home

API address

POST /v1.0/homes/{home_id}/rooms/{room_id}/devices

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

POST /v1.0/homes/123111/rooms/74332323/devices
{
	"device_ids":["ve23u9****","ve23u92****"]
}

Return example

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

Error code

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

API description

Modify a device in a room of a home

API address

PUT /v1.0/homes/{home_id}/rooms/{room_id}/devices

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

PUT /v1.0/homes/123111/rooms/74332323/devices
{
	"device_ids":["ve23u9****","ve23u92****"]
}

Return example

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

Error code

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 a home

API description

Delete a device in a room of the home

API address

DELETE /v1.0/homes/{home_id}/rooms/{room_id}/devices

Request parameter

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

Return parameter

Parameter name Data type Description
code Integer Response code. See Error code.
success Boolean Determine whether the request succeeded or not.
  • true: succeeded
  • false: failed
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.

Request example

DELETE /v1.0/homes/123111/rooms/74332323/devices
{
	"device_ids":["ve23u9****","ve23u92****"]
}

Return example

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

Error code

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