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.

1. 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.

Critical Data-Only Rule

NEVER guess, fabricate, or infer deviceId, endpointId, functionCode, or traitCode. Every value used in control calls MUST come from the cached data/devices.json file.

• endpointId must be taken from the device's endpoints[].endpointId.
• functionCode and traitCode must be taken from endpoints[].functions[].traits[].
• value type must match the trait definition.

Local Filtering (No Extra API Calls)

When the user asks for a subset of devices (for example, all lights, devices in the bedroom, or online switches):

• Filter the cached `data/devices.json` locally by deviceTypesList, name, state, or space.name / space.spatialMarking.
• Do not make a new API call to filter.

Device Type vs Device Name

• By Type (preferred): when the user asks for lights or switches, filter cached file by deviceTypesList.
• By Name (secondary): use device name only to select a specific device from the cached list.

Error Handling

• On errors with code 1001 (token expired) or 400 (bad params): re-check token, verify all IDs come from cached device data.
• On 2030: device not found; run bash scripts/fetch_all_devices.sh to refresh cache and retry.
• Timeout/network errors: retry once, then report.
• Cache file parse error: delete data/devices.json and run bash scripts/fetch_all_devices.sh to regenerate.

API Commands (7 total)

Device Management

#### Get all devices with space info — GetAllDevicesWithSpaceRequest

Retrieve all smart home devices in a single call, including full device info, space assignment, endpoints, functions, traits, and current values. No data field is needed (or data: null).

The agent MUST write this response to the local cache file (data/devices.json) and use the cache for all subsequent device queries, status checks, and as the basis for control commands. Use the provided script to fetch and cache:

bash scripts/fetch_all_devices.sh

Manual curl (for reference only — prefer the script):

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":"msg-'$(date +%s)'"}'

#### Get all device types — GetDeviceTypeInfosRequest

Retrieve every device type available in the current project. Each entry contains a deviceType code and its localized display name.

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

#### Control device — ExecuteTraitRequest

Control one or more device functions, such as turning on/off or adjusting level. endpointId, functionCode, and traitCode must be read from the cache.

# Turn on
curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteTraitRequest","version":"v1","msgId":"msg-'$(date +%s)'","data":[{"deviceId":"<deviceId>","endpointId":<endpointId>,"functionCode":"<functionCode>","traitCode":"OnOff","value":true}]}'

# Turn off
curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteTraitRequest","version":"v1","msgId":"msg-'$(date +%s)'","data":[{"deviceId":"<deviceId>","endpointId":<endpointId>,"functionCode":"<functionCode>","traitCode":"OnOff","value":false}]}'

Space Management

#### List space hierarchy — GetSpacesRequest

Retrieve all spaces as a hierarchical tree. Each space includes its ID, name, parent space ID, spatial marking label, and nested children.

Space request type hard rule: the request type for space listing is only GetSpacesRequest. Do not try GetAllSpacesRequest, GetSpaceListRequest, QuerySpaceListRequest, or any other guessed variant.

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

#### Create a new space — CreateSpaceRequest

Create a room, zone, or building. Omit parentSpaceId to create a top-level space. Run GetSpacesRequest first if the parent space ID is not known.

# Top-level space
curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"CreateSpaceRequest","version":"v1","msgId":"msg-'$(date +%s)'","data":{"name":"Living Room","spatialMarking":"living_room"}}'

# Sub-space
curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"CreateSpaceRequest","version":"v1","msgId":"msg-'$(date +%s)'","data":{"name":"Bedroom","parentSpaceId":"<parentSpaceId>","spatialMarking":"bedroom"}}'

#### Update space properties — UpdateSpaceRequest

Update the name or spatial marking of an existing space. Only provided fields are updated. spaceId is required.

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

#### Assign devices to a space — AssociateDevicesToSpaceRequest

Assign one or more devices to an existing space. Response data only contains failed items; empty means all succeeded.

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

Standard Operating Procedures (SOP)

SOP A: List or discover devices

1. Check whether data/devices.json exists and is non-empty.
2. If it exists: read device data directly from the file.
3. If it is missing or empty: run bash scripts/fetch_all_devices.sh to generate the cache, then read the file.
4. Answer the user's request by filtering the cache file.

SOP B: Query device state

1. Device state and trait values are already included in the cache file.
2. If data/devices.json is missing, run bash scripts/fetch_all_devices.sh first.
3. Find the device in the cache file and read the corresponding trait value.
4. No separate API call is needed to read device state.

SOP C: Control device

1. If data/devices.json is missing, run bash scripts/fetch_all_devices.sh first.
2. Read the exact deviceId, endpointId, functionCode, and traitCode from the cache file.
3. Use the ExecuteTraitRequest curl command with only cached values.
4. Response data only contains failed items; an empty array means all commands succeeded.

SOP D: Space management

1. Device-to-space associations are already included in data/devices.json.
2. Use the GetSpacesRequest curl command to retrieve the full space hierarchy tree.
3. Use CreateSpaceRequest, UpdateSpaceRequest, or AssociateDevicesToSpaceRequest as needed.

Cache Decision Tree

Does the user request involve devices, spaces, or types?
├── Yes → Check the local cache file `data/devices.json`
│   ├── Cache hit (file exists and is non-empty)
│   │   └── Read from the file directly and filter/aggregate locally
│   └── Cache miss / missing file
│       ├── Run `bash scripts/fetch_all_devices.sh`
│       ├── Re-read the cache file
│       └── Continue with the refreshed data
└── No → Continue with the normal flow

Does the task require device control?
├── Yes → Ensure `data/devices.json` exists (refresh first if missing)
│   ├── Read `deviceId + endpointId + functionCode + traitCode` from cache
│   └── Call `ExecuteTraitRequest` via curl
└── No → Return the cached data result

Did the user explicitly ask to refresh device data?
└── Run `bash scripts/fetch_all_devices.sh` to overwrite the cache, then re-read it

API Call Decision Tree

User wants devices by type?
  → data/devices.json exists? → Yes: filter file by deviceTypesList
                               → No:  bash scripts/fetch_all_devices.sh, then filter

User wants to list/discover all devices?
  → data/devices.json exists? → Yes: return full list from file
                               → No:  bash scripts/fetch_all_devices.sh, then read

User wants state of a device?
  → data/devices.json exists? → No: bash scripts/fetch_all_devices.sh
  → Read value from file: endpoints[].functions[].traits[].value

User wants to control a device?
  → data/devices.json exists? → No: bash scripts/fetch_all_devices.sh
  → Get deviceId + endpointId + functionCode + traitCode from file
  → curl ExecuteTraitRequest with correct value type

User wants devices by space/room?
  → data/devices.json exists? → Yes: filter file by space.name / spatialMarking
                               → No:  bash scripts/fetch_all_devices.sh, then filter

User wants to refresh device data?
  → bash scripts/fetch_all_devices.sh

User wants to see spaces?
  → curl GetSpacesRequest

User wants to create, update, or assign spaces?
  → curl GetSpacesRequest if a real spaceId is needed
  → then curl CreateSpaceRequest / UpdateSpaceRequest / AssociateDevicesToSpaceRequest

Forbidden Behavior

Files

• scripts/fetch_all_devices.sh — cache refresh script; calls GetAllDevicesWithSpaceRequest and writes data/devices.json
• data/devices.json — cache file generated by the script; contains complete device data
• references/examples.md — example curl invocations
• references/trait-codes.md — full list of trait codes with type, unit, read/write, subscribe flags

Keep this SKILL.md lean; consult references for details.