Smart Home Management

API list

action	Description
home.add	Add a home.
home.edit	Modify a home.
home.delete	Delete a home.
home.infos	Query information about a home.
home.devices	Query information about devices in a home.
home.addRoom	Add a room.
home.editRoom	Modify a room.
home.deleteRoom	Delete a room.
home.roomList	Query information about all rooms in a home.
home.roomDevices	Query all devices in a room.
home.memberAuthority	Grant permissions to home members.
home.deleteMember	Remove a member.
home.memberList	Query a list of home members.
home.memberInfos	Query information about all homes of a user.

Add home

API description

Add a home and rooms in the home to a user. If rooms is not set, only a home is added.

API endpoint

action: home.add

Request parameter

Parameter name	Type	Description	Required
uid	String	The user ID assigned by Tuya.	Yes
home	Object	The information about a home.	Yes
rooms	List	The name of the room.	No

Description of home

Parameter name	Type	Description	Required
name	String	The name of a home.	Yes
geo_name	String	The geographical location of a home.	No
lon	Double	The longitude.	No
lat	Double	The latitude.	No

Sample request

{
    "action":"home.add",
  "params":{
        "uid":"ay1528964101460qLVPu",
        "home":{
         "geo_name":"Xihu District, Hangzhou",
         "name":"My Home",
         "lat":30.1624,
         "lon":120.545
       },
    "rooms":[
      "Kitchen",
      "Bathroom"
    ]
  }
}

Response parameter

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

Sample response

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

Modify home

API description

Modify basic information about a home.

API endpoint

action: home.edit

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
name	String	The name of a home.	No
geo_name	String	The geographical location of a home.	No
lon	Double	The longitude.	No
lat	Double	The latitude.	No

Sample request

{
    "action":"home.edit",
  "params": {
    "home_id":3182004,
    "geo_name":"Hangzhou",
    "name":"My Home",
    "lat":30.1624,
    "lon":120.545
  }
}

Response parameter

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

Sample response

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

Delete home

API description

Delete a home device by home ID.

API endpoint

action: home.delete

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
    "action": "home.delete",
    "params": {
        "home_id": 3182004
    }
}

Response parameter

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

Sample response

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

Query home details

API description

Query information about a home by home ID.

API endpoint

action: home.infos

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
    "action": "home.infos",
    "params": {
        "home_id": 3182004
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
home_id	Long	The scene ID.
name	String	The name of a home.
geo_name	String	The geographical location of a home.
lon	Double	The longitude.
lat	Double	The latitude.

Sample response

{
 "success": true,
 "t": 1540955256215,
 "result": {
   "name": "Ming's Home",
   "lon": 120.545,
   "lat": 30.1624,
   "home_id": 3182004,
   "geo_name": "Hangzhou"
 }
}

Query devices in home

API description

Query information about devices in a home by home ID.

API endpoint

action: home.devices

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
    "action": "home.devices",
    "params": {
        "home_id": 3182004
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID (PID).
sub	Boolean	Indicates whether the device is sub-device. Valid values: - true: yes - false: no
uuid	String	The UUID of the specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
ip	String	The IP address of the device.
name	String	The name of the device.
time_zone	String	The ID of the time zone in which a device is located.
status	Object	The status of a DP.

Description of status

Parameter name	Type	Description
code	String	The code of the specified data point.
value	String	The value of a DP.

Sample response

{
    "success":true,
    "t":1541509099860,
    "result":[
        {
            "uuid":"vdevo153500827491970",
            "uid":"ay1528964101460qLVPu",
            "name":"xxx socket",
            "ip":null,
            "sub":false,
            "status":[
   {
       "code":"switch",
       "value":"true"
   },
   {
       "code":"countdown_1",
       "value":"0"
   }
            ],
            "category":"cz",
            "online":true,
            "id":"vdevo153500827491970",
            "time_zone":"+08:00",
            "local_key":"47a5a361719f16b9",
            "owner_id":"2422120",
            "product_id":"T62ZA4lyVXFgtvE7"
        },
        {
            "uuid":"vdevo154017769539389",
            "uid":"ay1528964101460qLVPu",
            "name": "All-in-one 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":"vdevo154017769539389",
            "time_zone":"+08:00",
            "local_key":"75bc0238e71ef011",
            "owner_id":"2422120",
            "product_id":"9ysAXds4ohDAnXwh"
        }
    ]
}

Add Room

API description

Add a room by home ID.

API endpoint

action: home.addRoom

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
name	String	The name of the room.	Yes

Sample request

{
    "action": "home.addRoom",
    "params": {
        "home_id": 3182004,
    "name": "Kitchen"
    }
}

Response parameter

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

Sample response

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

Modify Room

API description

Modify a room by home ID and room ID.

API endpoint

action: home.editRoom

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes
name	String	The name of the room.	Yes

Sample request

{
    "action": "home.editRoom",
    "params": {
        "home_id": 3182004,
    "room_id": 1408001,
    "name": "Kitchen"
    }
}

Response parameter

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

Sample response

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

Delete Room

API description

Delete a room by home ID and room ID.

API endpoint

action: home.deleteRoom

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes

Sample request

{
    "action": "home.deleteRoom",
    "params": {
        "home_id": 3182004,
    "room_id": 1408001
    }
}

Response parameter

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

Sample response

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

Query home and room details

API description

Query information about a home and rooms by home ID.

API endpoint

action: home.roomInfos

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
    "action": "home.roomInfos",
    "params": {
        "home_id": 3182004
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
home_id	Long	The scene ID.
name	String	The name of a home.
geo_name	String	The geographical location of a home.
lon	Double	The longitude.
lat	Double	The latitude.
rooms	List	The list of rooms.

Description of rooms

Parameter name	Type	Description
room_id	Long	The room ID.
name	String	The name of a room.

Sample response

{
    "success":true,
    "t":1540869200562,
    "result":{
        "home_id":3196002,
        "name":"Wang's home",
        "lon":120.545,
        "lat":30.1624,
        "geo_name":"Xihu District, Hangzhou",
        "rooms":[
            {
                "room_id":1398001,
                "name":"Kitchen"
            },
            {
                "room_id":1398002,
                "name":"Bathroom"
            }
        ]
    }
}

Add devices to room

API description

Add devices to a room in a home.

API endpoint

action: home.roomAddDevices

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes
device_ids	List	The list of target device IDs.	Yes

Sample request

{
    "action": "home.roomAddDevices",
    "params": {
        "home_id": 3182004,
        "room_id": 74332323,
    "device_ids": ["ve23u92932","ve23u929321"]
    }
}

Response parameter

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

Sample response

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

Error codes

The following table lists the error codes that might be returned when you make the API request. For more error codes, see Global Error Codes.

Error code	Description
500	System error. Contact the administrator.

Modify devices in room

API description

Modify devices in a room of a home.

API endpoint

action: home.roomEditDevices

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes
device_ids	List	The latest device IDs associated with a room.	Yes

Sample request

{
    "action": "home.roomEditDevices",
    "params": {
        "home_id": 3182004,
        "room_id": 74332323,
    "device_ids": ["ve23u92932","ve23u929321"]
    }
}

Response parameter

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

Sample response

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

Error codes

The following table lists the error codes that might be returned when you make the API request. For more error codes, see Global Error Codes.

Error code	Description
500	System error. Contact the administrator.

Remove devices from room

API description

Remove devices from a room in a home.

API endpoint

action: home.roomDeleteDevices

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes
device_ids	List	The list of target device IDs.	Yes

Sample request

{
    "action": "home.roomDeleteDevices",
    "params": {
        "home_id": 3182004,
        "room_id": 74332323,
    "device_ids": ["ve23u92932","ve23u929321"]
    }
}

Response parameter

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

Sample response

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

Error codes

The following table lists the error codes that might be returned when you make the API request. For more error codes, see Global Error Codes.

Error code	Description
500	System error. Contact the administrator.

Query all devices in room

API description

Query information about all devices in a room by home ID and room ID.

API endpoint

action: home.roomDevices

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
room_id	Long	The room ID.	Yes

Sample request

{
    "action": "home.roomDevices",
    "params": {
        "home_id": 3182004,
        "room_id": 1408001
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
id	String	The device ID.
uid	String	The user ID assigned by Tuya.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID (PID).
sub	Boolean	Indicates whether the device is sub-device. Valid values: - true: yes - false: no
uuid	String	The UUID of the specified device.
owner_id	String	The ID of the device owner.
online	Boolean	Indicates whether the device is online.
ip	String	The IP address of the device.
name	String	The name of the device.
time_zone	String	The ID of the time zone in which a device is located.
status	Object	The status of a DP.

Description of status

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

Sample response

{
    "success":true,
    "t":1541509099860,
    "result":[
        {
            "uuid":"vdevo153500827491970",
            "uid":"ay1528964101460qLVPu",
            "name":"xxx socket",
            "ip":null,
            "sub":false,
            "status":[
   {
       "code":"switch",
       "value":"true"
   },
   {
       "code":"countdown_1",
       "value":"0"
   }
            ],
            "category":"cz",
            "online":true,
            "id":"vdevo153500827491970",
            "time_zone":"+08:00",
            "local_key":"47a5a361719f16b9",
            "owner_id":"2422120",
            "product_id":"T62ZA4lyVXFgtvE7"
        },
        {
            "uuid":"vdevo154017769539389",
            "uid":"ay1528964101460qLVPu",
            "name":"All-in-one 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":"vdevo154017769539389",
            "time_zone":"+08:00",
            "local_key":"75bc0238e71ef011",
            "owner_id":"2422120",
            "product_id":"9ysAXds4ohDAnXwh"
        }
    ]
}

Grant permissions to member

API description

Grant administrator or non-administrator permissions to a home member and rename the member.

API endpoint

action: home.memberAuthority

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
uid	String	The user ID assigned by Tuya.	Yes
admin	Boolean	Set the member to be an administrator or non-administrator member. Valid values: - true: administrator. - false: non-administrator member.	Yes

Sample request

{
    "action": "home.memberAuthority",
    "params": {
        "home_id": 3182004,
    "uid": "ay15309353754999xY2T",
    "admin": false
    }
}

Response parameter

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

Sample response

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

Remove member

API description

Remove a member from a home.

API endpoint

action: home.deleteMember

Request parameter

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

Sample request

{
    "action": "home.deleteMember",
    "params": {
        "home_id": 3182004,
        "uid": "ay15309353754999xY2T"
    }
}

Response parameter

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

Sample response

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

Query home members

API description

Query a list of home members.

API endpoint

action: home.memberList

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
    "action": "home.memberList",
    "params": {
        "home_id": 3182004
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
uid	String	The user ID assigned by Tuya.
admin	Boolean	Indicates whether the member is the administrator. - true: yes - false: no
name	String	The username of the home member.
country_code	String	The country code of the home member.
menber_account	String	The account of the home member. Sensitive data is masked.

Sample response

{
    "success":true,
    "t":1540799929837,
    "result":[
        {
            "country_code":"86",
            "member_account":"18******176",
            "uid":"ay1528964101460qLVPu",
            "admin":true,
            "name":"Hua"
        },
        {
            "country_code":"86",
            "member_account":"15******196",
            "uid":"ay15309353754999xY2T",
            "admin":false,
            "name":"Ming"
        }
    ]
}

Query all homes of user

API description

Query information about all homes of a user by uid.

API endpoint

action: home.memberHomeList

Request parameter

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

Sample request

{
    "action": "home.memberHomeList",
    "params": {
        "uid": "ay15309353754999xY2T"
    }
}

Response parameter

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

Description of result

Parameter name	Type	Description
home_id	Long	The home ID.
name	String	The name of a home.
geo_name	String	The geographical location of a home.
lon	Double	The longitude.
lat	Double	The latitude.

Sample response

{
    "success":true,
    "t":1541508940996,
    "result":[
        {
            "name":"Hometown",
            "lon":120.100791,
            "lat":30.270856,
            "home_id":2422120,
            "geo_name":"Westlake"
        },
        {
            "name":"My home",
            "lon":120.090286,
            "lat":30.303958,
            "home_id":3177459,
            "geo_name":"Longjing"
        },
        {
            "name":"My home",
            "lon":120.545,
            "lat":30.1624,
            "home_id":3196002,
            "geo_name":"Hangzhou"
        }
    ]
}