Automation API

Query Device Traits Available for Automation

By calling this API, you can query trait information that can be used for automation from all devices. The returned content includes the value type, unit, and the applicable phase for each trait in the automation process (such as starter, condition, or action).

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Message type for the request, must be `QueryAutomationCapabilitiesRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Request ID defined by you.
data	Object	✗	Pass an empty object here.

Example Request

Below is a sample request body for QueryAutomationCapabilitiesRequest:

{
    "type": "QueryAutomationCapabilitiesRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {}
}

Response Parameters

Parameter	Type	Description
type	String	The message type of the response, always `QueryAutomationCapabilitiesResponse`.
version	String	Response version. It matches the version used in the request.
msgId	String	The `msgId` provided in your request.
code	Number	Return code. `0` means success, any non-zero value indicates failure.
data.devices	Array of Object	List of device information.
data.devices[].deviceId	String	Device ID.
data.devices[].deviceName	String	Device name.
data.devices[].endpoints	Array of Object	List of endpoint information for the device.
data.devices[].endpoints[].endpointName	String	Endpoint name.
data.devices[].endpoints[].endpointId	Number	Endpoint ID.
data.devices[].endpoints[].properties	Array of Object	List of traits.
data.devices[].endpoints[].properties[].functionCode	String	Function code.
data.devices[].endpoints[].properties[].functionName	String	Function name.
data.devices[].endpoints[].properties[].traitCode	String	Trait code.
data.devices[].endpoints[].properties[].traitName	String	Trait name.
data.devices[].endpoints[].properties[].valueType	String	The value type of the trait (such as boolean, number, etc.).
data.devices[].endpoints[].properties[].semanticRole	Array of String	The automation phases this trait can participate in, including starter, condition, and action. The specific roles depend on the returned array.
data.devices[].endpoints[].properties[].unit	String/null	Unit. If no unit, this is null.

Example Response

Below is an example response for QueryAutomationCapabilitiesResponse:

{
    "type": "QueryAutomationCapabilitiesResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "devices": [
            {
                "deviceId": "9f3e3632068ff047",
                "deviceName": "Door and Window Magnet Sensor",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            {
                "deviceId": "af9e93b709de1fd9",
                "deviceName": "Motion Sensor",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            {
                "deviceId": "947793560f5b2fbd",
                "deviceName": "Flood Detector",
                "endpoints": [
                    {
                        "endpointName": "Endpoint_2",
                        "endpointId": 2,
                        "properties": [
                            {
                                "functionCode": "OnOffSensor",
                                "functionName": "OnOff Sensor",
                                "traitCode": "BooleanState",
                                "traitName": "Boolean State",
                                "valueType": "boolean",
                                "semanticRole": [
                                    "starter",
                                    "condition"
                                ],
                                "unit": null
                            }
                        ]
                    }
                ]
            },
            ...
        ]
    },
    "code": 0
}

Create Automation

By calling this API, you can create and enable a flow automation.

Once created successfully, you can view and manage this flow in the automation list on Aqara Studio.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Message type, must be `CreateAutomationRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Custom request ID defined by you.
data	Object	✓	Request data.
data.definitionType	String	✓	Automation type. Currently, only `"SCRIPT_JSON"` is supported.
data.config	Object	✓	JSON automation script. For details, see JSON Automation Script.

Example Request

Below is a sample request body for CreateAutomationRequest:

{
    "type": "CreateAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "definitionType": "SCRIPT_JSON",
        "config": {
            "metadata": {
                "name": "Smart Lighting Control",
                "description": "Automatically turn on two lights when the switch is on",
                "scope": [
                    {
                        "name": "switchState",
                        "type": "device.property",
                        "deviceId": "switch001",
                        "endpointId": 1,
                        "functionCode": "OnOff",
                        "traitCode": "OnOff"
                    },
                    {
                        "name": "tempSensor",
                        "type": "device.property",
                        "deviceId": "sensor001",
                        "endpointId": 1,
                        "functionCode": "TemperatureMeasurement",
                        "traitCode": "MeasuredValue"
                    }
                ]
            },
            "automations": [
                {
                    "name": "Switch triggers light linkage",
                    "starters": [
                        {
                            "type": "property.event",
                            "source": {
                                "type": "data.ref",
                                "from": "/metadata/scope",
                                "select": {
                                    "by": "name",
                                    "value": "switchState"
                                }
                            },
                            "is": true,
                            "for": "5sec",
                            "suppressFor": "10sec"
                        }
                    ],
                    "condition": {
                        "type": "and",
                        "conditions": [
                            {
                                "type": "property.state",
                                "source": {
                                    "type": "data.ref",
                                    "from": "/metadata/scope",
                                    "select": {
                                        "by": "name",
                                        "value": "tempSensor"
                                    }
                                },
                                "greaterThan": 20
                            },
                            {
                                "type": "time.between",
                                "after": "08:00",
                                "before": "22:00"
                            }
                        ]
                    },
                    "actions": [
                        {
                            "type": "device.trait.write",
                            "functionCode": "Switch",
                            "traitCode": "OnOff",
                            "targets": [
                                {
                                    "deviceId": "light001",
                                    "endpointIds": [1]
                                }
                            ],
                            "value": true
                        },
                        {
                            "type": "delay",
                            "for": "2sec"
                        },
                        {
                            "type": "device.trait.write",
                            "functionCode": "LevelControl",
                            "traitCode": "CurrentLevel",
                            "targets": [
                                {
                                    "deviceId": "light001",
                                    "endpointIds": [1]
                                }
                            ],
                            "value": 100
                        }
                    ]
                }
            ]
        }
    }
}

Response Parameters

Parameter	Type	Description
type	String	The type of message in the response. Always set to `CreateAutomationResponse`.
version	String	Response version. It matches the version used in the request.
msgId	String	The `msgId` provided in your request.
code	Number	Return code. `0` means success, any non-zero value indicates failure.
message	String	Description of the request result.
data	String	The automatin ID of the created automation.

Example Response

Below is an example response for CreateAutomationResponse:

{
    "type": "CreateAutomationResponse",
	"version": "v1",
	"msgId": "1751609244328",
	"code": 0,
	"message": "",
    "data": "auto_15b0cde_127312348967862272"
}

Edit Automation

By calling this API, you can modify the name and enabled status of an existing automation. If the automation's definitionType is "SCRIPT_JSON", you can also update its automation script content at the same time.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Message type, must be `UpdateAutomationRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Custom request ID defined by you.
data	Object	✓	Request data.
data.automationId	String	✓	The target automation ID.
data.definitionType	String	✓	The definition type of the target automation to be edited.
data.name	String	✗	The new name.
data.enabled	Boolean	✗	The new enabled status. `true` means enabled. `false` means disabled.
data.config	Object	✗	The new JSON automation script.
data.updateMask	Array of String	✓	List of parameter names to be updated. Only the following fields are supported: `"name"` `"enabled"` `"config"` Please make sure each item in `updateMask` has a corresponding new value provided in the data object.

Example Request

Below is an example of the request body for UpdateAutomationRequest:

{
    "type": "UpdateAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationId":"auto_15b0cde_127312348967862272",
        "definitionType": "SCRIPT_JSON",
        "name": "New Name",
        "updateMask": [
            "name"
        ]
    }
}

Response Parameters

Parameter	Type	Description
type	String	The type of message in the response. Always set to `UpdateAutomationResponse`.
version	String	Response version. It matches the version used in the request.
msgId	String	The `msgId` provided in your request.
code	Number	Return code. `0` means success, any non-zero value indicates failure.
message	String	Description of the request result.
data	String	Empty string.

Example Response

The following is an example response for UpdateAutomationResponse:

{
    "type": "UpdateAutomationResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "code": 0,
    "message": "",
    "data": ""
}

Batch Update Automation Status

By calling this API, you can update the enable status of multiple automations at once.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Type of request message, must be `UpdateAutomationStatusRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Custom request ID defined by you.
data	Object	✓	Request data object.
data.automationIds	Array of String	✓	List of automation IDs to update the status for.
data.enabled	Boolean	✓	The status to set: `true` to enable, `false` to disable.

Example Request

Below is a example request body for UpdateAutomationStatusRequest:

{
    "type": "UpdateAutomationStatusRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationIds": [
            "auto_15b0cde_127312348967862272"
        ],
        "enabled": false
    }
}

Response Parameters

Parameter	Type	Description
type	String	Response message type, always `UpdateAutomationStatusResponse`.
version	String	API version in the response, always `v1`.
msgId	String	The `msgId` you provided in the request.
code	Number	Indicates whether the request was successful: 0 for success, non-zero for failure.
message	String	Description of the request result.
data	Object	Response data object.
data.successIds	Array of String	List of successfully updated automation IDs.
data.failedItems	Array of Object	List of failed automation update objects.
data.failedItems.automationId	String	Automation ID.
data.failedItems.code	Number	Error code.
data.failedItems.message	String	Failure description.

Example Response

The following is an example response for UpdateAutomationStatusResponse:

{
    "type": "UpdateAutomationStatusResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "successIds": [
            "auto_15b0cde_127312348967862272"
        ]
    }
}

Query Automation List

By calling this API, you can get a paginated list of automation summaries, including each automation's ID, name, enable status, and creation time.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Message type, must be `GetAutomationListRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Custom request ID defined by you.
data	Object	✓	Request data.
data.definitionTypes	Array of String	✗	Target types to query. Optional values: `"SCRIPT_JSON"`, `"SCRIPT_TEXT"`, `"WHEN_IF_THEN"`. If not provided or empty, queries all types.
data.orderBy	String	✗	Sorting field. `"createTime asc"`: (default) sort by creation time in ascending order `"createTime desc"`: sort by creation time in descending order
data.pageNum	Number	✓	Page number, starting from 1.
data.pageSize	Number	✓	Number of items per page.

Example Request

Below is a sample request body for GetAutomationListRequest:

{
    "type": "GetAutomationListRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "definitionTypes": ["SCRIPT_JSON"],
        "pageNum":1,
        "pageSize":2
    }
}

Response Parameters

Parameter	Type	Description
type	String	Response message type, always `GetAutomationListResponse`.
version	String	API version in the response, always `v1`.
msgId	String	The `msgId` you provided in the request.
data	Object	Response data object, including the automation list and pagination info.
data.totalCount	Number	Total number of automations.
data.pageNum	Number	Current page number.
data.pageSize	Number	Number of items per page.
data.data	Array of Object	List of automations.
data.data[].automationId	String	Automation ID.
data.data[].definitionType	String	Automation type.
data.data[].name	String	Name of the automation.
data.data[].enabled	Boolean	Enable status: true: enabled false: disabled
data.data[].createTime	Number	Creation time of the automation, as a UTC timestamp in milliseconds.
code	Number	Indicates request success. 0 means success, non-zero means failure.
message	String or null	Description of the response. An empty string or null indicates success.

Example Response

Below is an example response for GetAutomationListResponse:

{
    "type": "GetAutomationListResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "totalCount": 6,
        "pageNum": 1,
        "pageSize": 2,
        "data": [
            {
                "automationId": "auto_15b0cde_127312348967862272",
                "definitionType": "SCRIPT_JSON",
                "name": "a3-1",
                "enabled": false,
                "createTime": 1766043229326
            },
            {
                "automationId": "auto_15b0ceb_127312523723538432",
                "definitionType": "SCRIPT_JSON",
                "name": "b2",
                "enabled": true,
                "createTime": 1766043270999
            }
        ]
    },
    "code": 0,
    "message": null
}

Query Automation Details

By calling this API and providing the automation ID, you can retrieve the detailed information for the specified automation (such as the JSON automation script).

tip

Only automations with definitionType equal to "SCRIPT_JSON" are supported for querying details.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Request message type, must be `GetAutomationDetailsRequest`.
version	String	✓	API version, must be `v1`.
msgId	String	✓	Custom request ID defined by you.
data	String	✓	The automation ID to be queried.

Example Request

Below is an example request body for GetAutomationDetailsRequest:

{
    "type": "GetAutomationDetailsRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": "auto_15b0cde_127312348967862272"
}

Response Parameters

Parameter	Type	Description
type	String	The type of response message. Always set to `GetAutomationDetailsResponse`.
version	String	API version. Always `v1`.
msgId	String	The `msgId` provided in your request.
data	Object	The returned object containing the automation's detailed information.
data.automationId	String	The automation ID.
data.definitionType	String	Automation type. Currently always `"SCRIPT_JSON"`.
data.name	String	The name of the automation.
data.enabled	Boolean	Whether the automation is enabled.
data.config	Object	The JSON automation script.
data.createTime	Number	The time when the automation was created, as a UTC timestamp in milliseconds.
code	Number	Response code. 0 means success, any other value is an error code.
message	String or null	Description message about the response. An empty string or null means the request was successful.

Example Response

Below is an example response for GetAutomationDetailsResponse:

{
    "type": "GetAutomationDetailsResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "data": {
        "automationId": "auto_15b0cde_127312348967862272",
        "definitionType": "SCRIPT_JSON",
        "name": "a3-1",
        "enabled": false,
        "config": {
            ...
        },
        "createTime": 1766043229326
    },
    "code": 0,
    "message": null
}

Delete Automation

By calling this API, you can delete multiple automations.

Request Parameters

Parameter	Type	Required	Description
type	String	✓	Request message type, fixed as `DeleteAutomationRequest`.
version	String	✓	API version, always `v1`.
msgId	String	✓	Custom request ID defined by you.
data	Array of String	✓	Array of automation IDs to be deleted.

Example Request

Below is an example request body for DeleteAutomationRequest:

{
    "type": "DeleteAutomationRequest",
    "version": "v1",
    "msgId": "1751609244328",
    "data": ["auto_15b0b4d_1273030749213163"]
}

Example Response

Parameter	Type	Description
type	String	The type of message in the response. Always set to `DeleteAutomationResponse`.
version	String	Response version. Always set to `v1`.
msgId	String	The `msgId` provided in your request.
code	Number	Return code. `0` means success, any non-zero value indicates failure.
message	String	Description of the request result.
data	Object	Response object.
data.successIds	Array of String	IDs of automations deleted successfully.
data.failedItems	Array of Object	Objects representing failed deletions.
data.failedItems.automationId	String	Automation ID.
data.failedItems.code	Number	Error code.
data.failedItems.message	String	Failure description.

Example Response

{
    "type": "DeleteAutomationResponse",
    "version": "v1",
    "msgId": "1751609244328",
    "code": 0,
    "message": "",
    "data": {
        "successIds": [
            "auto_15b0b4d_1273030749213163"
        ]
    }
}

Query Device Traits Available for Automation​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Create Automation​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Edit Automation​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Batch Update Automation Status​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Query Automation List​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Query Automation Details​

Request Parameters​

Example Request​

Response Parameters​

Example Response​

Delete Automation​

Request Parameters​

Example Request​

Example Response​

Example Response​

Query Device Traits Available for Automation

Request Parameters

Example Request

Response Parameters

Example Response

Create Automation

Request Parameters

Example Request

Response Parameters

Example Response

Edit Automation

Request Parameters

Example Request

Response Parameters

Example Response

Batch Update Automation Status

Request Parameters

Example Request

Response Parameters

Example Response

Query Automation List

Request Parameters

Example Request

Response Parameters

Example Response

Query Automation Details

Request Parameters

Example Request

Response Parameters

Example Response

Delete Automation

Request Parameters

Example Request

Example Response

Example Response