REST API

仅 Cloud

云端 REST API 位于 https://api.adhf.dev。自托管用户可以访问本地 API —— 参见 Self-hosted API。

本页记录托管云自动化界面。

它不尝试涵盖：

• 诸如 /api/v1/status 之类的本地 standalone 端点
• 诸如 session-host 恢复之类的自托管运行时操作者流程
• 诸如 /api/v1/mux/* 之类的本地终端 mux 端点

对于这些内容，请改用 OSS 自托管文档。

认证

所有 API 请求都需要在 Authorization 头中提供一个 API 密钥：

curl -H "Authorization: Bearer adk_..." \
     https://api.adhf.dev/api/v1/daemons

注意： 当前版本不支持通过仪表板签发 API 密钥。现有密钥仍可继续使用。如需访问，请联系支持。

对于常规的云自动化，API 密钥是主要的认证界面。

一些敏感的云账户变更现在需要一次近期的浏览器登录，而非 API 密钥认证。这些路由期望一个新鲜的仪表板 JWT 会话，当用 API 密钥或陈旧会话调用时会返回 403 RECENT_LOGIN_REQUIRED。

当前受近期登录保护的路由：

• POST /api/v1/webhooks
• PATCH /api/v1/webhooks/{webhookId}
• DELETE /api/v1/webhooks/{webhookId}
• POST /api/v1/webhooks/{webhookId}/test
• POST /api/v1/daemons/{daemonId}/disconnect
• POST /api/v1/daemons/{daemonId}/revoke

权限范围

范围	说明
ide:read	列出守护进程、读取 IDE 状态
ide:control	启动/停止 IDE、发送守护进程命令
agent:read	读取聊天消息、代理状态
agent:control	发送消息、批准/拒绝操作
terminal:exec	在机器上执行终端命令
webhook:manage	检查投递，并在近期仪表板登录后管理 webhook

公开 API 结构

对于大多数云集成，请按以下层次思考：

• GET /api/v1/daemons 查找已连接的机器
• GET /api/v1/daemons/{daemonId}/status 检查机器和会话状态
• /api/v1/shortcuts/* 用于你实际想要的常见代理操作
• /api/v1/webhooks/* 用于向你自己的系统投递事件

除非你特别需要原始的守护进程命令路由器，否则请优先使用 Shortcuts。

所有守护进程和 shortcut 路由都限定在已认证云账户所拥有的机器和会话范围内。提供其他账户的守护进程或合成会话 id 会返回 404，而不会跨越账户边界。

---

守护进程

管理已连接的机器（守护进程）及其 IDE。

列出守护进程

GET /api/v1/daemons

范围： ide:read

返回所有已连接的机器及其托管的 IDE、CLI 和 ACP 代理。

响应：

{
  "daemons": [
    {
      "id": "c79baa8f...",
      "hostname": "M1-Server",
      "nickname": "작업용",
      "platform": "darwin",
      "cdpConnected": true,
      "ides": [
        { "id": "c79baa8f:ide:cursor_myproject", "type": "cursor", "cdpConnected": true }
      ],
      "clis": [
        { "id": "c79baa8f:cli:gemini-cli", "type": "gemini-cli", "name": "Gemini CLI" }
      ],
      "acps": [
        { "id": "c79baa8f:acp:claude-acp", "type": "claude-acp" }
      ]
    }
  ]
}

获取守护进程状态

GET /api/v1/daemons/{daemonId}/status

范围： ide:read

返回详细的守护进程状态，包括 IDE/CLI 状态、工作区信息和代理活动。

发送守护进程命令

POST /api/v1/daemons/{daemonId}/command

范围： ide:control

向目标机器发送一个直接命令。

对于大多数集成，请优先使用下面的 Shortcuts API。POST /daemons/:id/command 是更底层的应急出口。

请求体：

{
  "type": "send_chat",
  "payload": { "message": "Hello!" }
}

可用命令类型

命令	目标	负载	说明
send_chat	IDE/CLI	message	发送一条聊天消息
read_chat	IDE/CLI	—	读取当前聊天内容
resolve_action	IDE/CLI	action	批准/拒绝代理操作
screenshot	IDE	width?	截取一张截图
launch_ide	守护进程	ideType, enableCdp?	启动一个 IDE
launch_cli	守护进程	cliType, dir?, model?	启动 CLI/ACP 会话
stop_cli	守护进程	cliType	停止 CLI 会话

内部路由器中并非每个命令都适合放入公开自动化材料。如果你在构建一个常规集成，请保持在已记录的命令集或 shortcut 端点上。

执行终端命令

POST /api/v1/daemons/{daemonId}/terminal

范围： terminal:exec

在守护进程机器上执行一个终端命令。

请求体：

{
  "command": "ls -la",
  "name": "my-terminal",
  "cwd": "/home/user"
}

断开守护进程

POST /api/v1/daemons/{daemonId}/disconnect

范围： ide:control

强制断开守护进程。守护进程可以自动重连。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

撤销守护进程令牌

POST /api/v1/daemons/{daemonId}/revoke

范围： ide:control

永久撤销守护进程的连接令牌。需要在机器上重新运行 adhdev setup。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

---

Shortcuts

面向最常见代理操作的便捷端点。

启动 IDE / CLI / ACP

POST /api/v1/shortcuts/{daemonId}/launch

范围： ide:control

请求体：

IDE

{ "type": "cursor" }

CLI

{ "type": "gemini-cli", "dir": "/path/to/project" }

ACP

{ "type": "claude-acp", "dir": "/path", "model": "opus" }

停止 CLI / ACP

POST /api/v1/shortcuts/{daemonId}/stop

范围： ide:control

请求体：

{ "type": "gemini-cli" }

发送聊天消息

POST /api/v1/shortcuts/{ideId}/chat

范围： agent:control

向 AI 代理发送一条消息。ideId 是守护进程/会话状态 API 返回的机器范围目标 ID，包括诸如 {daemonId}:session:{sessionId} 之类的合成会话路由。

这是外部自动化的默认发送路径。

请求体（旧版文本形式）：

{ "message": "Fix the bug in auth.ts" }

请求体（规范信封形式）：

{
  "input": {
    "parts": [
      { "type": "text", "text": "Fix the bug in auth.ts" }
    ],
    "textFallback": "Fix the bug in auth.ts"
  }
}

可选 —— 为多代理 IDE 指定代理类型：

{ "message": "Fix the bug", "agentType": "cursor" }

你必须提供 message 或 input 之一。

读取聊天

GET /api/v1/shortcuts/{ideId}/chat

范围： agent:read

从代理读取当前聊天内容。可选地按 ?agentType=cursor 过滤。

聊天调试包

GET /api/v1/shortcuts/{ideId}/chat/debug
POST /api/v1/shortcuts/{ideId}/chat/debug

范围： agent:read

为当前聊天/会话构建一个有界、已脱敏的调试包。守护进程生成权威的提供方/解析器/会话/终端证据；POST 可以包含一个仪表板 frontendSnapshot，用当前渲染的前端状态对其进行补充。

POST 的可选请求体：

{ "agentType": "hermes", "frontendSnapshot": { "activeConversation": { "sessionId": "session_..." } } }

响应包含 bundle 和可直接复制的 text。密钥和凭据默认会被脱敏。

批准 / 拒绝操作

POST /api/v1/shortcuts/{ideId}/approve

范围： agent:control

批准或拒绝一个待处理的代理操作。

请求体：

{ "action": "approve" }

或

{ "action": "reject", "agentType": "cursor" }

获取代理状态

GET /api/v1/shortcuts/{ideId}/status

范围： agent:read

返回当前状态（idle、generating、waiting_approval、error）、存在时的提供方摘要元数据/控件，以及工作区信息。

Webhook

管理用于实时事件通知的 webhook 订阅。设置说明和签名验证请参见 Webhook 功能指南。

列出 Webhook

GET /api/v1/webhooks

范围： webhook:manage

创建 Webhook

POST /api/v1/webhooks

范围： webhook:manage

请求体：

{
  "url": "https://example.com/hook",
  "events": ["agent:generating_completed", "agent:waiting_approval"]
}

使用 ["*"] 订阅所有事件。响应包含一个用于签名验证的 secret（只显示一次）。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

切换 Webhook

PATCH /api/v1/webhooks/{webhookId}

范围： webhook:manage

请求体：

{ "active": false }

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

删除 Webhook

DELETE /api/v1/webhooks/{webhookId}

范围： webhook:manage

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

列出投递

GET /api/v1/webhooks/{webhookId}/deliveries?limit=20

范围： webhook:manage

返回最近的投递历史，包含状态码、响应体和计时。

测试 Webhook

POST /api/v1/webhooks/{webhookId}/test

范围： webhook:manage

向 webhook URL 发送一个测试 webhook:test 事件。

这是一个受近期登录保护的云操作。API 密钥和陈旧的浏览器会话会收到 403 RECENT_LOGIN_REQUIRED。

---

事件

这些事件会被投递给 webhook，并同时驱动实时云通知流程。

事件	说明
agent:generating_started	代理开始生成响应
agent:generating_completed	代理完成生成（包含以秒为单位的 duration）
agent:waiting_approval	代理正在等待用户批准
agent:error	代理遇到错误
machine:connected	机器上线
machine:disconnected	机器下线

事件负载

{
  "event": "agent:generating_completed",
  "ideId": "c79baa8f:ide:cursor_myproject",
  "ideType": "cursor",
  "duration": 12.5,
  "timestamp": 1710000000000
}

---

典型流程

最常见的 API 流程是：

1. 用 GET /api/v1/daemons 列出机器
2. 从守护进程状态负载中挑选一个目标代理
3. 用 POST /api/v1/shortcuts/{ideId}/chat 发送一条消息
4. 轮询 GET /api/v1/shortcuts/{ideId}/status 或使用 webhook
5. 用 GET /api/v1/shortcuts/{ideId}/chat 读取对话记录

本页排除的内容

如果你在寻找以下任何内容，那这是错误的 API 页面：

• standalone 的 GET /api/v1/status
• standalone 的 POST /api/v1/command
• 托管本地 CLI 会话的运行时快照/事件端点
• 终端 mux 工作区端点

这些属于 Self-hosted API。

---

速率限制

单请求限制

限制	值
API 密钥	每分钟 120 个请求
IP 地址	每分钟 60 个请求
认证端点	每 5 分钟 10 个请求
命令超时	60 秒

每月调用限制

套餐	每月 API 调用
Free	1,000
Pro	50,000
Team	500,000
Enterprise	无限

---

错误代码

状态	代码	说明
400	—	请求错误（验证失败）
401	AUTH_REQUIRED	缺少 Authorization 头
401	AUTH_INVALID	无效或已过期的 API 密钥
403	AUTH_FORBIDDEN	API 密钥缺少所需的范围
403	RECENT_LOGIN_REQUIRED	敏感的云操作需要一次新鲜的仪表板登录，而非 API 密钥认证或陈旧会话
404	—	未找到守护进程/资源、已过期的邀请/共享，或目标不属于已认证账户
429	RATE_LIMITED	超出每分钟速率限制
429	API_LIMIT_EXCEEDED	达到每月 API 调用限制
500	—	命令发送失败（守护进程离线）
503	—	守护进程已连接但 WebSocket 已断开
504	—	命令响应超时（超过 60 秒）