Data Export API v1

Aqara provides the Data Export API v1, which allows you to access device data from the Studio system and perform secondary development.

The API supports querying and subscribing to device data, device control, device add/delete event notifications, and scene list queries.

Communication Protocols

The Studio API supports two main protocols: HTTP and WebSocket.

Request Details

The request URL format varies depending on whether remote access is enabled.

HTTP Request URL

Request method: POST
Request URL format:

• Remote access disabled: http://<local_LAN_IP>/open/api/v1
• Remote access enabled: http://<remote_access_address>/open/api/v1

WebSocket Request URL

Request URL format:

• Remote access disabled: ws://<local_LAN_IP>/open/ws
• Remote access enabled: ws://<remote_access_address>/open/ws

After you establish a connection, you can send and receive JSON messages in real time with the server.

Request Headers

Parameter	Type	Required	Description
Authorization	String	Required for HTTP and WebSocket	Authorization Token for user authentication. Format is Bearer <token>. Replace <token> with the token you obtained from Aqara Studio. (If the token from Aqara Studio already includes the Bearer prefix, use it directly without adding another Bearer.) For more details on how to get the token, see Developer Guide - Obtain Required Information.
Content-Type	String	HTTP only	Default is application/json.

API List

Aqara Studio determines and responds to different API functions based on the type field in the request body. The table below summarizes all supported APIs in Aqara Studio, along with their corresponding request and response types:

API Function	Request Type	Response Type
Query Device IDs by Pages	GetDeviceInfoRequest	GetDeviceInfoResponse
Query All Device IDs	GetAllDeviceInfoRequest	GetAllDeviceInfoResponse
Query Device Spec Configuration	GetDevicesRequest	GetDevicesResponse
Query All Device IDs
Control Device	ExecuteTraitRequest	ExecuteTraitResponse
Query the Latest Values of Device Traits	GetTraitValueRequest	GetTraitValueResponse
Subscribe to Multiple Trait Changes	SubscribeTraitValueRequest	SubscribeTraitValueResponse
Unsubscribe from Trait Changes	UnsubscribeTraitValueRequest	UnsubscribeTraitValueResponse
Subscribe to All Trait Changes	SubscribeAllRequest	SubscribeAllResponse
Unsubscribe from All Trait Changes	UnsubscribeAllRequest	UnsubscribeAllResponse
Object Event Messages Push	-	objectEvent
Query Device History	QueryDeviceHistoryDataRequest	QueryDeviceHistoryDataResponse
Create Automation	CreateScriptAutomationRequest	CreateScriptLinkageResponse
Edit Automation Script	UpdateScriptAutomationRequest	UpdateScriptAutomationResponse
Modify Automation Name and Enable Status	UpdateScriptAutomationRequest	UpdateScriptAutomationResponse
Query Automation List	GetScriptAutomationListRequest	GetScriptAutomationListResponse
Query Automation Details	GetScriptAutomationDetailsRequest	GetScriptAutomationDetailsResponse
Delete Automation	DeleteAutomationRequest	DeleteAutomationResponse

Error Handling

If you receive an error response after making an API request, don’t worry. The error message will help you troubleshoot and solve the issue.

Below is an example to help you quickly understand and resolve problems:

{
    "type": "ErrorMessage",
    "version": "v1",
    "msgId": "UNKNOWN",
    "code": 1000,
    "message": "Message parsing failed: Unexpected JSON token at offset 0: Serializer for subclass 'GetDeviceInfo' is not found in the polymorphic scope of 'WebSocketMessageRequest' at path: $\nCheck if class with serial name 'GetDeviceInfo' exists and serializer is registered in a corresponding SerializersModule.\nTo be registered automatically, class 'GetDeviceInfo' has to be '@Serializable', and the base class 'WebSocketMessageRequest' has to be sealed and '@Serializable'.\nJSON input: {\n    \"type\": \"GetDeviceInfo\",....."
}

1. Check the type field

   First, look at the type field in the response. All failed requests will have ErrorMessage as the value.

2. Check the msgId field

   If there was a format error in your request, the msgId will usually be UNKNOWN, which means the server did not recognize a valid request ID.

3. Carefully read the message field for details

   The message field provides detailed error information. It usually includes the most important clues, for example, missing parameters or data type mistakes. Read this carefully to figure out the precise issue and how to fix it.