Aqara Gateway API
APIs for managing gateway subdevice pairing, binding, and unbinding operations
APIs for managing gateway subdevice pairing, binding, and unbinding operations
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/aqara:aqara-gateway-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Aqara Gateway API
version: v1
termsOfService: https://domain.com/terms
x-internal: true
description: 'Operations tagged Gateway across 2 of this provider''s published API definitions: data-export-api-en.yaml, data-export-api-zh.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{host}/open/api/v1'
description: Data Export API endpoint
variables:
host:
description: 'Please enter your Aqara Studio service address. This can be a local LAN address (http) or a remote access address (https).
For example:
- http://10.11.50.56
- https://xxx.edge-xxx.aqara.com/
'
default: <Aqara_Studio_URL>
security:
- BearerAuth: []
tags:
- name: Gateway
description: APIs for managing gateway subdevice pairing, binding, and unbinding operations
paths:
/gateways:
get:
tags:
- Gateway
summary: List Gateways
description: 'Query all Matter gateways and Zigbee gateways in Aqara Studio.
:::tip
Not all Zigbee gateways support all Zigbee sub-devices.
:::'
operationId: getGateways
x-skill-intent: gateway.list
x-idempotent: true
x-retryable: true
x-side-effects: none
parameters:
- name: state
in: query
description: Gateway online status.
required: false
schema:
type: boolean
- name: protocols
in: query
description: 'List of protocol types. URL example: `protocols=zigbee,matter`, or `protocols=zigbee&protocols=matter`.'
required: false
schema:
type: array
items:
type: string
enum:
- zigbee
- matter
style: form
explode: true
responses:
'200':
description: Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/GatewaysResponse'
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
servers:
- url: '{host}/open/api/v1'
description: Data Export API endpoint
variables:
host:
description: 'Please enter your Aqara Studio service address. This can be a local LAN address (http) or a remote access address (https).
For example:
- http://10.11.50.56
- https://xxx.edge-xxx.aqara.com/
'
default: <Aqara_Studio_URL>
/gateways/subdevices/join:
post:
tags:
- Gateway
summary: Enable Sub-device Joining
description: 'Call this API to make a specified Zigbee gateway enter subdevice join mode.
:::tip
Before starting, please ensure that the Zigbee subdevice is already in pairing mode.
:::'
operationId: joinSubdevice
x-skill-intent: gateway.subdevice.join
x-idempotent: false
x-retryable: conditional
x-side-effects: device_state_change
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubdeviceJoinRequest'
examples:
zigbeeJoin:
summary: Standard Zigbee device pairing (e.g., triple-click to join)
value:
gatewayId: gateway001
commandCode: APIEnableSubdeviceJoining
responses:
'200':
description: Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/SubdeviceJoinResponse'
examples:
success:
value:
type: SubdeviceJoinResponse
version: v1
msgId: 2df2f431-a58d-4fdb-b39c-4f0d29e7ecf9
code: 0
message: success
fail:
value:
type: SubdeviceJoinResponse
version: v1
msgId: 2df2f431-a58d-4fdb-b39c-4f0d29e7ecfa
code: 2201
message: invalid security code
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
servers:
- url: '{host}/open/api/v1'
description: Data Export API endpoint
variables:
host:
description: 'Please enter your Aqara Studio service address. This can be a local LAN address (http) or a remote access address (https).
For example:
- http://10.11.50.56
- https://xxx.edge-xxx.aqara.com/
'
default: <Aqara_Studio_URL>
/gateways/subdevices/join/stop:
post:
tags:
- Gateway
summary: Disable Sub-device Joining
description: Call this API to have a specified Zigbee gateway exit sub-device addition mode.
operationId: stopSubdeviceJoin
x-skill-intent: gateway.subdevice.join.stop
x-idempotent: true
x-retryable: true
x-side-effects: device_state_change
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubdeviceJoinStopRequest'
examples:
stopJoin:
value:
gatewayId: gateway001
responses:
'200':
description: Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
examples:
success:
value:
type: SubdeviceJoinStopResponse
version: v1
msgId: 2df2f431-a58d-4fdb-b39c-4f0d29e7ecfb
code: 0
message: success
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
servers:
- url: '{host}/open/api/v1'
description: Data Export API endpoint
variables:
host:
description: 'Please enter your Aqara Studio service address. This can be a local LAN address (http) or a remote access address (https).
For example:
- http://10.11.50.56
- https://xxx.edge-xxx.aqara.com/
'
default: <Aqara_Studio_URL>
/gateways/subdevices/bindResult:
post:
tags:
- Gateway
summary: Query Sub-device Joining Results
description: Query the joining results of specified sub-devices. Flexible filtering is supported via `protocols` (protocol types) and `gatewaySubdeviceFilters` (filter conditions for gateways and their sub-devices). Multiple protocols and multiple gateway/sub-device combinations can be queried at the same time.
operationId: getDeviceBindResult
x-skill-intent: device.bind.result
x-idempotent: true
x-retryable: true
x-side-effects: none
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceBindResultRequest'
examples:
queryByGatewayAndSubDevices:
value:
protocols:
- zigbee
- matter
gatewaySubdeviceFilters:
- gatewayId: gateway-001
subDeviceIds: []
- gatewayId: gateway-001
subDeviceIds:
- subdevice-001
- subdevice-002
- gatewayId: gateway-002
subDeviceIds:
- subdevice-101
responses:
'200':
description: Request succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceBindResultResponse'
examples:
bindResultSuccess:
value:
type: DeviceBindResultResponse
version: v1
msgId: 2df2f431-a58d-4fdb-b39c-4f0d29e7ecfb
code: 0
message: success
data:
- deviceId: subdevice-001
deviceName: Bedroom Temperature Sensor
protocols:
- zigbee
gatewayId: gateway-001
code: 0
message: null
bindTime: 1710001235000
- deviceId: subdevice-002
deviceName: null
protocols:
- matter
gatewayId: gateway-001
code: 0
message: null
bindTime: 1710001236000
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
'500':
$ref: '#/components/responses/InternalServerErrorResponse'
servers:
- url: '{host}/open/api/v1'
description: Data Export API endpoint
variables:
host:
description: 'Please enter your Aqara Studio service address. This can be a local LAN address (http) or a remote access address (https).
For example:
- http://10.11.50.56
- https://xxx.edge-xxx.aqara.com/
'
default: <Aqara_Studio_URL>
components:
schemas:
ErrorResponse:
description: Error response. Read code and message for details.
allOf:
- $ref: '#/components/schemas/BaseResponse'
BaseResponse:
type: object
required:
- type
- version
- msgId
- code
properties:
type:
type: string
description: Message type
version:
type: string
description: API version
example: v1
msgId:
type: string
description: Message ID
code:
type: integer
description: Business status code, 0 indicates success
message:
type: string
description: Message
DeviceBindResultResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DeviceBindResultItem'
example:
type: DeviceBindResultResponse
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-000000000017
code: 0
message: success
data:
- deviceId: subdevice-001
deviceName: Bedroom Temperature Sensor
protocols:
- zigbee
gatewayId: gateway-001
code: 0
message: null
bindTime: 1710001235000
SubdeviceJoinRequest:
type: object
required:
- gatewayId
- commandCode
properties:
gatewayId:
type: string
description: Gateway ID
commandCode:
type: string
enum:
- APIEnableSubdeviceJoining
description: 'Command codes for sub-device joining:
- `APIEnableSubdeviceJoining`: Standard Zigbee device joining (e.g. triggered by pressing a button to enter join mode)
'
data:
type: object
description: 'Network joining parameters (JSON object). Depending on the commandCode, the required parameters are as follows:
- `APIEnableSubdeviceJoining`: No need to provide this field.
'
DeviceBindResultItem:
type: object
required:
- deviceId
- protocols
- gatewayId
- bindTime
properties:
deviceId:
type: string
description: Sub-device ID
deviceName:
type:
- string
- 'null'
description: Sub-device name
space:
$ref: '#/components/schemas/DeviceSpace'
description: Space where the sub-device is located
protocols:
type: array
items:
type: string
enum:
- zigbee
- matter
description: List of supported protocols
gatewayId:
type: string
description: Associated gateway ID
code:
type:
- integer
- 'null'
description: Error code (returned on failure)
message:
type:
- string
- 'null'
description: Error message (returned on failure)
bindTime:
type: integer
format: int64
description: Join timestamp (milliseconds, UTC)
SubdeviceJoinResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
example:
type: SubdeviceJoinResponse
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-000000000011
code: 0
message: success
GatewayInfo:
type: object
required:
- deviceId
- deviceName
properties:
deviceId:
type: string
description: Gateway device ID.
deviceName:
type: string
description: Gateway device name.
supportZigbee:
type: boolean
description: Whether it supports Zigbee. Default or null means that it does not support Zigbee.
supportedMatterRoles:
type:
- integer
- 'null'
description: 'Supported Matter roles. Missing or null means not supported.
This field is a bitmask. Use `supportedMatterRoles & <role value> != 0` to check if a specific role is supported:
- 1: Matter controller
- 2: Matter commissioner
- 4: Thread border router
- 8: Matter bridge
For example, `supportedMatterRoles & 2 != 0` means Matter sub-device commissioning is supported.
'
space:
$ref: '#/components/schemas/DeviceSpace'
description: Space where the gateway is located.
GatewaySubdeviceDidFilter:
type: object
required:
- gatewayId
properties:
gatewayId:
type: string
description: Gateway ID
subDeviceIds:
type:
- array
- 'null'
description: 'List of subdevice IDs.
- If empty or omitted: Query all subdevices under the specified gateway.
- If not empty: Query the specified subdevices under the specified gateway.
'
items:
type: string
SubdeviceJoinStopRequest:
type: object
required:
- gatewayId
properties:
gatewayId:
type: string
description: Gateway ID
DeviceSpace:
type: object
required:
- parentSpaceId
- spaceId
- name
properties:
parentSpaceId:
type: string
description: Parent space ID
spaceId:
type: string
description: Space ID
name:
type: string
description: Space name
GatewaysResponse:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GatewayInfo'
example:
type: GetGatewaysResponse
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-00000000000e
code: 0
message: success
data:
- deviceId: gateway-001
deviceName: Living Room Gateway M2
supportZigbee: true
supportedMatterRoles: 1
DeviceBindResultRequest:
type: object
required:
- gatewaySubdeviceFilters
properties:
protocols:
type:
- array
- 'null'
description: Specifies the protocol types of subdevices to query. If not provided, there is no restriction on protocol types.
items:
type: string
enum:
- zigbee
- matter
gatewaySubdeviceFilters:
type: array
description: Filters (Gateway ID and Subdevice ID)
required: true
items:
$ref: '#/components/schemas/GatewaySubdeviceDidFilter'
ErrorResponse_2:
description: 错误响应,错误信息通过 code 与 message 提供
allOf:
- $ref: '#/components/schemas/BaseResponse_2'
BaseResponse_2:
type: object
required:
- type
- version
- msgId
- code
properties:
type:
type: string
description: 消息类型
version:
type: string
description: 接口版本
example: v1
msgId:
type: string
description: 消息 ID
code:
type: integer
description: 业务状态码,0 表示成功
message:
type: string
description: 提示信息
DeviceBindResultResponse_2:
allOf:
- $ref: '#/components/schemas/BaseResponse_2'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DeviceBindResultItem_2'
example:
type: DeviceBindResultResponse
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-000000000017
code: 0
message: success
data:
- deviceId: subdevice-001
deviceName: 卧室温度传感器
protocols:
- zigbee
gatewayId: gateway-001
code: 0
message: null
bindTime: 1710001235000
SubdeviceJoinRequest_2:
type: object
required:
- gatewayId
- commandCode
properties:
gatewayId:
type: string
description: 网关设备 ID。
commandCode:
type: string
enum:
- APIEnableSubdeviceJoining
description: '入网命令编码:
- `APIEnableSubdeviceJoining`: 标准 Zigbee 设备入网(例如通过按键触发入网模式)。
'
data:
type: object
description: '入网参数(JSON 对象),根据不同的 commandCode,需传入的参数说明如下:
- `APIEnableSubdeviceJoining`: 无需传入此字段。
'
DeviceBindResultItem_2:
type: object
required:
- deviceId
- protocols
- gatewayId
- bindTime
properties:
deviceId:
type: string
description: 子设备 ID。
deviceName:
type:
- string
- 'null'
description: 子设备名称。
space:
$ref: '#/components/schemas/DeviceSpace_2'
description: 子设备所在空间。
protocols:
type: array
items:
type: string
enum:
- zigbee
- matter
description: 入网协议集合。
gatewayId:
type: string
description: 所属网关 ID。
code:
type:
- integer
- 'null'
description: 错误码(失败时返回)。
message:
type:
- string
- 'null'
description: 错误信息(失败时返回)。
bindTime:
type: integer
format: int64
description: 入网时间戳(毫秒级 UTC 时间戳)。
GatewayInfo_2:
type: object
required:
- deviceId
- deviceName
properties:
deviceId:
type: string
description: 网关设备 ID。
deviceName:
type: string
description: 网关设备名称。
supportZigbee:
type: boolean
description: 是否支持 Zigbee,缺省或 null 为不支持。
supportedMatterRoles:
type:
- integer
- 'null'
description: '支持的 Matter 角色,缺少或 null 为不支持。
该字段为位掩码,使用 `supportedMatterRoles & 角色值 != 0` 判断是否支持对应角色:
- 1:Matter controller
- 2:Matter commissioner
- 4:Thread border router
- 8:Matter bridge
例如 `supportedMatterRoles & 2 != 0` 表示支持 Matter 子设备入网。
'
space:
$ref: '#/components/schemas/DeviceSpace_2'
description: 网关所在空间。
GatewaySubdeviceDidFilter_2:
type: object
required:
- gatewayId
properties:
gatewayId:
type: string
description: 网关设备 ID。
subDeviceIds:
type:
- array
- 'null'
description: '子设备 ID 列表。
- 为空或不传:查询指定网关下的全部子设备
- 非空:查询指定网关下的指定子设备
'
items:
type: string
SubdeviceJoinStopRequest_2:
type: object
required:
- gatewayId
properties:
gatewayId:
type: string
description: 网关设备 ID。
DeviceSpace_2:
type: object
required:
- parentSpaceId
- spaceId
- name
properties:
parentSpaceId:
type: string
description: 父空间 ID
spaceId:
type: string
description: 空间 ID
name:
type: string
description: 空间名称
GatewaysResponse_2:
allOf:
- $ref: '#/components/schemas/BaseResponse_2'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GatewayInfo_2'
example:
type: GetGatewaysResponse
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-00000000000e
code: 0
message: success
data:
- deviceId: gateway-001
deviceName: 客厅网关M2
supportZigbee: true
supportedMatterRoles: 1
DeviceBindResultRequest_2:
type: object
required:
- gatewaySubdeviceFilters
properties:
protocols:
type:
- array
- 'null'
description: 指定待查询的子设备协议类型。不传时,表示不限制协议类型。
items:
type: string
enum:
- zigbee
- matter
gatewaySubdeviceFilters:
type: array
description: 过滤条件(网关 ID 与子设备 ID)
required: true
items:
$ref: '#/components/schemas/GatewaySubdeviceDidFilter_2'
responses:
InternalServerErrorResponse:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000006
code: 500
message: Internal server error
UnauthorizedResponse:
description: Unauthorized or authentication expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000002
code: 401
message: Token expired. Please generate a new token
TooManyRequestsResponse:
description: Request frequency too high
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000005
code: 429
message: Request frequency too high
NotFoundResponse:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000004
code: 404
message: Resource not found
ForbiddenResponse:
description: No permission to access
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000003
code: 403
message: No permission to access this resource
BadRequestResponse:
description: Request parameter error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000001
code: 400
message: Parameter xxx is required
InternalServerErrorResponse_2:
description: 服务内部错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000006
code: 500
message: 服务内部异常
UnauthorizedResponse_2:
description: 未认证或认证失效
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000002
code: 401
message: token 已过期,请重新生成 token
TooManyRequestsResponse_2:
description: 请求频率过高
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000005
code: 429
message: 请求频率过高
NotFoundResponse_2:
description: 资源不存在
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000004
code: 404
message: 资源不存在
ForbiddenResponse_2:
description: 无权限访问
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000003
code: 403
message: 无权限访问该资源
BadRequestResponse_2:
description: 请求参数错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
example:
type: ErrorMessage
version: v1
msgId: a1b2c3d4-e5f6-7890-abcd-err000000001
code: 400
message: 参数 xxx 不能为空
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Authorization: Bearer token'
x-refined-from:
- data-export-api-en.yaml
- data-export-api-zh.yaml