Aqara Open API

Aqara Open API Skill

This skill equips the agent to operate Aqara/Lumi Studio smart home devices via HTTPS requests to the Aqara Open Platform API. All operations are performed exclusively through curl commands, except GetAllDevicesWithSpaceRequest, which must be executed through bash scripts/fetch_all_devices.sh to refresh the local cache file data/devices.json.

This skill supports only:

• device discovery and device type lookup
• device state queries from cache
• device control
• space listing, creation, update, and device assignment

Configuration

The following environment variables are required:

• AQARA_ENDPOINT_URL: The base URL
• AQARA_OPEN_API_TOKEN: Your Long-Lived Access Token.

AI Quick Navigation (Read This First)

This section is a navigation and execution summary only. It does not add new rules or change existing constraints.

What This Skill Can Do

• Device discovery: load all devices, space mappings, endpoints, functions, traits, and current values
• Device type catalog: query all device types in the project with code and display name
• Device queries: filter by type, name, room/space, or online status; read current trait values
• Device control: send control requests using real deviceId, endpointId, functionCode, and traitCode from cache
• Space management: list spaces, create spaces, update spaces, and assign devices to spaces

Intent to Fastest Path

• List all devices / devices by type / devices in a room / device state
  • Check data/devices.json
  • If cache exists: read the file
  • If cache is missing: run bash scripts/fetch_all_devices.sh
• Control a device
  • Ensure data/devices.json exists
  • Read deviceId + endpointId + functionCode + traitCode from cache
  • Then use bash + curl for ExecuteTraitRequest
• What device types are there?
  • Use bash + curl for GetDeviceTypeInfosRequest
• Refresh all device data
  • Only run bash scripts/fetch_all_devices.sh
• List spaces
  • Use bash + curl for GetSpacesRequest
• Create or update a space
  • First get the real spaceId from GetSpacesRequest
  • Then call CreateSpaceRequest or UpdateSpaceRequest
• Assign devices to a space
  • First get the real spaceId from GetSpacesRequest
  • Read real deviceId values from data/devices.json
  • Then call AssociateDevicesToSpaceRequest

Six Highest-Priority Rules

1. All-device loading only goes through the script: GetAllDevicesWithSpaceRequest may only be executed via bash scripts/fetch_all_devices.sh.
2. All other requests only go through curl: except for the refresh script above, every other API call must use bash + curl.
3. Request bodies may only contain four fields: type, version, msgId, and data; version must always be "v1".
4. type is whitelist-only: use only the exact request types listed in this document; never test guessed alternatives such as GetAllSpacesRequest, GetSpaceListRequest, or QuerySpaceListRequest.
5. All IDs and codes must come from real API data: never guess deviceId, endpointId, functionCode, traitCode, or spaceId.

Required Preconditions

• Before listing devices, reading state, or filtering by room/type: check whether data/devices.json exists
• Before controlling a device: obtain the real deviceId, endpointId, functionCode, and traitCode from the cache file
• Before creating or updating a space: if spaceId is needed, call GetSpacesRequest first
• Before assigning devices to a space: get spaceId from GetSpacesRequest and deviceId values from data/devices.json

Terms and Field Reference

• Cache file: data/devices.json, which stores the data array from GetAllDevicesWithSpaceRequest
• deviceId: device identifier used for control and space assignment
• endpointId: endpoint identifier, only from cached endpoints[].endpointId
• functionCode / traitCode: capability identifiers from cache
• spaceId: space identifier from GetSpacesRequest or cached space.spaceId

Section Index

• Protocol and four-field request body: see ## API Protocol
• Script vs curl execution rules: see ### Execution Model
• Cache file rules: see ### File Cache Model (Cache-First Data Model)
• Device APIs: see ## API Commands under ### Device Management
• Space APIs: see ### Space Management
• Standard workflows: see ## Standard Operating Procedures (SOP)
• Decision trees: see ## Cache Decision Tree and ## API Call Decision Tree
• Forbidden behavior: see ## Forbidden Behavior
• Trait code reference: see references/trait-codes.md

1. Role and Core Philosophy

Role: You are a strict hardware interface controller. Never infer or guess IDs or capability fields.

2. Hard Safety Rules

2.1 Valid Value Rule

Any operation involving live device state, such as power, brightness, or temperature, must follow this rule:

Never produce logically inconsistent output such as "the light is off but brightness is 100%".

Quick Start (Operator)

1. Set environment variables:

• AQARA_OPEN_API_TOKEN: your Aqara Open API Bearer token (JWT)
• AQARA_ENDPOINT_URL: the API base URL

Real environment value rule: AQARA_ENDPOINT_URL and AQARA_OPEN_API_TOKEN must be read from the runtime environment (via $AQARA_ENDPOINT_URL and $AQARA_OPEN_API_TOKEN). Do not guess, fabricate, or use example placeholders as real request values. If either variable is missing or empty, tell the user to configure it first.

2. Test connectivity:

curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"GetAllDevicesWithSpaceRequest","version":"v1","msgId":"test-1"}'

API Protocol

Base URL: $AQARA_ENDPOINT_URL

All requests use a single unified POST endpoint. Routing is determined by the type field in the JSON body.

Request Envelope

The request-body JSON may contain exactly these 4 fields. Do not add, remove, or replace fields:

{
  "type": "<RequestType>",
  "version": "v1",
  "msgId": "<unique-id>",
  "data": { ... }
}

Strict request-body constraints

1. Do not omit version: every curl request body must include "version":"v1".
2. Do not add undefined fields: the request body may contain only these 4 keys. Do not add senderId, source, timestamp, or any field not defined in this document.
3. Do not invent field names or structures: neither the top-level body nor data may contain made-up fields or undocumented shapes.
4. Do not invent or trial-run alternate type values: if this document says the request type is GetSpacesRequest, then type must be exactly GetSpacesRequest.
5. Do not use synonym or variant guessing for type: names such as GetAllSpacesRequest, GetSpaceListRequest, QuerySpaceListRequest, ListSpacesRequest, or other self-created variants are forbidden unless they are explicitly documented in this file.

Required Headers

Authorization: Bearer $AQARA_OPEN_API_TOKEN
Content-Type: application/json

Response Envelope

{
  "type": "<ResponseType>",
  "version": "v1",
  "msgId": "<matching-id>",
  "code": 0,
  "message": null,
  "data": { ... }
}

code: 0 = success. Non-zero = error. Common error codes:

• 400: invalid parameters
• 1001: token expired
• 2030: device not found

curl Template

The -d value for every curl request must be a JSON object with only 4 keys: type, version, msgId, and data. Replace <TYPE> with the API method name and <DATA> with the correct payload:

curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"<TYPE>","version":"v1","msgId":"msg-'$(date +%s)'","data":<DATA>}'

Always keep "version":"v1" in -d, and never add senderId or any other field not defined in this document.

How the Agent Should Use This Skill

Execution Model

Execution rules (must follow):

• Only GetAllDevicesWithSpaceRequest: execute it via bash scripts/fetch_all_devices.sh. The script calls the API and writes the response data to data/devices.json. Do not call this request directly with curl.
• All other supported API requests (such as ExecuteTraitRequest, GetSpacesRequest, CreateSpaceRequest, UpdateSpaceRequest, and AssociateDevicesToSpaceRequest): execute them with bash + curl. The JSON body must contain exactly 4 keys: type, version, msgId, and data.
• No exploratory type retries: when a request fails, do not try nearby or similar type names. Verify the documented type, payload shape, token, IDs, cache, and required preconditions, then retry the same documented request only if appropriate.

File Cache Model (Cache-First Data Model)

Local cache file

• data/devices.json — the data array from GetAllDevicesWithSpaceRequest, including complete device information: deviceId, name, deviceTypesList, state, space, endpoints, and all functions/traits/current values

Refresh cache (create/overwrite cache file)

bash scripts/fetch_all_devices.sh

Usage rules (must follow)

1. Read cache first: when the user asks for device lists, device types, room mappings, or basic device information, check whether data/devices.json exists and is non-empty.
2. Cache hit: if the cache file exists, read the file directly and continue. Do not call GetAllDevicesWithSpaceRequest again.
3. Cache miss / missing file / parse failure: run bash scripts/fetch_all_devices.sh to refresh the cache. After refresh, re-read the cache file before continuing.
4. Explicit refresh requested by the user: run bash scripts/fetch_all_devices.sh and then re-read the file.
5. Control commands (ExecuteTraitRequest) still go directly to the API via curl, but all deviceId / endpointId / functionCode / traitCode values must come from the cache file.