REST API 文档

AI-First 设计,所有接口响应自带自然语言摘要

基础 URL:https://peiot.net/api/ai/v1

认证方式

通过 HTTP Header 传递 API Key:

请求头
X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

权限等级:read(读取)、write(写入)、control(控制设备)

错误码

错误码HTTP说明
0200成功
40001401API Key 缺失
40002401API Key 无效或已禁用
40010403权限不足
40011403设备不在白名单
42901429请求频率超限(每分钟)
42902429请求次数超限(每日)
44001404设备不存在
44002404无数据
50002503设备离线

GET /Ping/index

健康检查接口,无需认证。

请求
curl https://peiot.net/api/ai/v1/Ping/index

GET /Devices/index

获取设备列表,含在线状态和数据快照。权限:read

参数类型说明
pageint页码,默认 1
page_sizeint每页条数,默认 20,最大 100
onlineint在线过滤:1=仅在线,0=仅离线

GET /Devices/realtime

获取设备实时数据(温湿度气压 + 体感温度/露点/舒适度)。权限:read

参数类型说明
passkeystring设备 passkey(32位),必填

GET /Devices/history

查询历史数据,支持多粒度。权限:read

参数类型说明
passkeystring设备 passkey,必填
startint起始时间戳(秒),必填
endint结束时间戳(秒),必填
granularitystringminute / quarter / hour / day,默认自动
fieldsstring指定字段,逗号分隔

GET /Devices/status

获取设备状态(电量、信号、存储、内存等)。权限:read

参数类型说明
passkeystring设备 passkey,必填

GET /Devices/summary

获取自然语言环境摘要,AI 可直接引用。权限:read

参数类型说明
passkeystring设备 passkey,必填
detailstringbrief / normal / detailed,默认 normal

POST /Command/send

下发设备命令,通过 MQTT CMD 通道。权限:control

参数类型说明
passkeystringQuery 参数,设备 passkey,必填
cmdstringBody,命令名称(白名单内)
paramsobjectBody,命令参数,可选
timeoutintBody,等待超时 1-30秒,默认10

POST /Command/sample

触发立即采样,返回最新数据。权限:control

参数类型说明
passkeystringQuery 参数,设备 passkey,必填

POST /Deviceconfig/update

修改设备配置。权限:write

参数类型说明
passkeystringQuery 参数,设备 passkey,必填
fast_uploadboolBody,开启/关闭高速上传
timezone_offsetintBody,时区偏移(秒)