API

外部 API 用于让业务系统向指定电脑发送自动化命令。云端验证身份、保存 Device Inbox 消息并转发状态摘要，不执行插件、浏览器或助手工具。

创建调用凭证

在“开发者 → API 凭证”中创建 Service Account 或 API Key，并只授予需要的范围：

automation:list
automation:execute
run:read
artifact:request
device:dev_123

密钥只在创建时显示一次，数据库只保存哈希。可以设置有效期、IP 白名单、设备和自动化范围。

发起执行

POST /api/v1/devices/{device_id}/automations/{automation_id}/execute
Authorization: Bearer <api-key>
Idempotency-Key: <unique-key>
Content-Type: application/json

{
  "inputs": {},
  "fail_if_offline": false,
  "queue_ttl_seconds": 600
}

服务端先返回消息状态，不把“已投递”误报为“已执行成功”：

{
  "message_id": "msg_123",
  "delivery_status": "pending_device",
  "target_device_id": "dev_123"
}

设备收到后会创建本地 Run。调用方通过查询或事件订阅查看 received、started、completed、failed 等真实状态。

幂等

相同 Idempotency-Key 不会重复创建远程消息，本地还会按 message_id 再次去重。对发布、发送、删除等有副作用的操作，仍需遵循插件自身的幂等和结果核验规则。

设备离线

• fail_if_offline=true：设备离线时立即返回失败。
• queue_ttl_seconds：在有效期内等待设备上线，过期后不执行。

隐私模式

标准模式下服务器需要校验输入 JSON。高隐私模式可以用设备公钥加密输入，云端只保存密文，由目标电脑解密。

API 文档和参数校验来自设备同步的最小 Remote Catalog，其中只包含名称、Input/UI Schema、版本和远程权限，不包含插件执行步骤、Cookie、Profile 或 Secret。