Smart Home Management

Last Updated on : 2024-06-05 03:15:11download

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