GridCMS API 文档
从您的设备与脚本上报数据，读取历史记录与配置。GridCMS 的 API 与 emoncms 完全一致—— 已有 emoncms 集成代码可零改动迁移。本文示例以云服务地址 cloud.gridcms.cn 为例， 私有化部署时请替换为您自己的域名。
两把密钥，各管一件事
登录控制台「账号 → API 密钥」即可获取。请妥善保管读写密钥，泄露后请立即重置。
只读密钥 READ-ONLY
仅可读取数据与配置。可安全用于仪表盘前端、分享链接与第三方展示系统，即使泄露也无法写入或修改数据。
读写密钥 READ & WRITE
允许设备向您的账户上报数据，并可创建、修改 Feed 与处理链。仅保存在设备端或服务器端，切勿放入公开前端代码。
三种密钥传递方式（任选其一）
| 方式 | 示例 | 说明 |
|---|---|---|
| POST Body（推荐） | apikey=APIKEY | 密钥不进入 URL 与访问日志，最安全 |
| 请求头 | Authorization: Bearer APIKEY | 标准 Bearer 认证，推荐服务端调用使用 |
| URL 参数 | &apikey=APIKEY | 调试与只读场景便捷；注意 URL 会被代理日志记录 |
设备不支持 HTTPS？GridCMS 与 emoncms 一样支持 AES-128-CBC 加密上报——以 API 密钥作为预共享密钥加密报文，明文不出设备。
发送您的第一条数据，
只需 三步
无需安装任何东西，一个浏览器就能完成。
复制请求地址
下面这条请求向名为 meter01 的设备写入一路 power = 100。登录控制台后，示例中的密钥会自动替换为您的读写密钥。
在浏览器新标签页打开
服务器返回 {"success": true}，确认数据已被接收。
看数据到达
新的 Input 会立即出现在「Inputs」页面，点击 Log to Feed 即可开始持久化存储并上图。
设备数据上报
Input 只保存最新值并作为数据流起点；历史存储请在控制台配置 Log to Feed，或通过 Feed API 创建。
| 方法 | 路径 | 说明与主要参数 |
|---|---|---|
| GET / POST | /input/post | 写入一个节点的数据。参数：node（节点名）、fulljson={"key":value}（JSON 多值）或 json=v1,v2（CSV 简写）、time（可选，Unix 秒） |
| GET / POST | /input/bulk | 批量补传，断网缓存恢复场景专用。参数：data=[[time,node,v1,v2,…],…]，支持 offset / sentat 校准时间偏移 |
| GET | /input/list | 列出全部 Input 及最新值。可加 node 参数过滤单个节点 |
| POST | /input/process/set | 为指定 Input 设置处理链（ProcessList）：inputid + processlist |
时序数据的存与取
Feed 是持久化的时序曲线。存储引擎 PHPFINA（固定间隔）或 PHPTIMESERIES（可变间隔）。
| 方法 | 路径 | 说明与主要参数 |
|---|---|---|
| POST | /feed/create | 新建 Feed：name、tag、engine（PHPFINA / PHPTIMESERIES）、interval（秒，PHPFINA 必填） |
| GET | /feed/list | 列出全部 Feed：id、名称、引擎、最新值、更新时间 |
| GET | /feed/data.json | 读取历史：id、start / end（Unix 毫秒，支持 -86400000 等相对值）、interval（聚合间隔秒）、average、skipmissing、limitinterval |
| GET | /feed/value | 读取单个 Feed 最新值：id |
| GET | /feed/fetch | 一次取多个 Feed 最新值：ids=1,2,3（只读密钥可用） |
按模板批量初始化设备
设备库内置电表 / 传感器等常用模板：初始化一次，Inputs、Feeds 与处理链自动配齐。
| 方法 | 路径 | 说明与主要参数 |
|---|---|---|
| GET | /device/list | 设备列表：名称、类型、所属节点、在线状态 |
| POST | /device/create | 创建设备：name、type（模板名）、node |
| POST | /device/init | 按模板初始化：自动生成 Inputs、Feeds 与 ProcessList，幂等可重复执行 |
| GET | /device/template/list | 可用模板清单（含用户自定义扩展模板） |
轮询之外，还有推送
GridCMS 内置 MQTT 代理，实时数据按 emon/<node>/<key> 主题发布。GridBox 格物 网关默认即通过 MQTT 上云；您的前端或第三方系统也可直接订阅。
响应与错误
所有接口返回 JSON。成功：{"success": true} 或数据本体；失败：{"success": false, "message": "…"}。常见错误：密钥无效（401）、参数缺失（400）、Feed 不存在（404）。
机器可读版本
本参考提供机器可读格式，直接交给 AI 编程助手即可生成集成代码：/llms.txt；API 参考的 Markdown 与 OpenAPI JSON 版本即将上线（/api.md、/api.json 占位）。
