REST API

Cloud Only

クラウド REST API は https://api.adhf.dev で提供されます。セルフホストのユーザーはローカル API にアクセスできます — Self-hosted API を参照してください。

このページは、ホスト型クラウド自動化のサーフェスを文書化します。

次のものは カバーしません:

/api/v1/status などのローカル standalone エンドポイント
session-host の復旧などのセルフホストランタイムのオペレーターフロー
/api/v1/mux/* などのローカルターミナル mux エンドポイント

それらについては、代わりに OSS セルフホストドキュメントを使ってください。

認証

すべての API リクエストには、Authorization ヘッダーに API キーが必要です:

bash

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 を優先してください。

すべてのデーモンおよびショートカットのルートは、認証されたクラウドアカウントが所有するマシンとセッションにスコープされます。別のアカウントのデーモンや合成セッション ID を渡すと、アカウントの境界を越える代わりに 404 を返します。

Daemons

接続されたマシン（デーモン）とその IDE を管理します。

List Daemons

http

GET /api/v1/daemons

Scope: ide:read

管理されている IDE、CLI、ACP エージェントとともに、接続されたすべてのマシンを返します。

Response:

json

{
  "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 Daemon Status

http

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

Scope: ide:read

IDE/CLI の状態、ワークスペース情報、エージェントのアクティビティを含む、詳細なデーモンのステータスを返します。

Send Daemon Command

http

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

Scope: ide:control

対象のマシンに直接コマンドを送ります。

ほとんどの統合では、下の Shortcuts API を優先してください。POST /daemons/:id/command は、より低レベルのエスケープハッチです。

Body:

json

{
  "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`	Daemon	`ideType, enableCdp?`	IDE を起動
`launch_cli`	Daemon	`cliType, dir?, model?`	CLI/ACP セッションを開始
`stop_cli`	Daemon	`cliType`	CLI セッションを停止

内部ルーターのすべてのコマンドが、公開自動化の資料に属するわけではありません。通常の統合を構築している場合は、文書化されたコマンドセットまたはショートカットエンドポイントに留まってください。

Execute Terminal Command

http

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

Scope: terminal:exec

デーモンマシン上でターミナルコマンドを実行します。

Body:

json

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

Disconnect Daemon

http

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

Scope: ide:control

デーモンを強制的に切断します。デーモンは自動的に再接続できます。

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

Revoke Daemon Token

http

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

Scope: ide:control

デーモンの接続トークンを永久に取り消します。マシンで再度 adhdev setup を実行する必要があります。

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

Shortcuts

最も一般的なエージェントアクションのための便利なエンドポイント。

Launch IDE / CLI / ACP

http

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

Scope: ide:control

Body:

IDECLIACP

json

{ "type": "cursor" }

json

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

json

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

Stop CLI / ACP

http

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

Scope: ide:control

Body:

json

{ "type": "gemini-cli" }

Send Chat Message

http

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

Scope: agent:control

AI エージェントにメッセージを送ります。ideId は、デーモン/セッションステータス API が返すマシンスコープのターゲット ID で、{daemonId}:session:{sessionId} のような合成セッションルートを含みます。

これは、外部自動化のためのデフォルトの送信経路です。

Body（レガシーのテキスト形式）:

json

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

Body（正規のエンベロープ形式）:

json

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

オプション — マルチエージェント IDE のためにエージェントタイプを指定します:

json

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

message または input のいずれかを指定する必要があります。

Read Chat

http

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

Scope: agent:read

エージェントから現在のチャット内容を読みます。オプションで ?agentType=cursor によってフィルタリングします。

Chat Debug Bundle

http

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

Scope: agent:read

現在のチャット/セッションのための、境界付きでサニタイズされたデバッグバンドルをビルドします。デーモンが正式なプロバイダー/パーサー/セッション/ターミナルの証拠を生成します。POST は、現在レンダリングされているフロントエンドの状態でそれを補完するために、ダッシュボードの frontendSnapshot を含めることができます。

POST のためのオプションボディ:

json

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

レスポンスには bundle とコピーしやすい text が含まれます。シークレットと認証情報はデフォルトで秘匿されます。

Approve / Reject Action

http

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

Scope: agent:control

保留中のエージェントアクションを承認または拒否します。

Body:

json

{ "action": "approve" }

または

json

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

Get Agent Status

http

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

Scope: agent:read

現在のステータス（idle、generating、waiting_approval、error）、存在する場合はプロバイダーのサマリーメタデータ/コントロール、およびワークスペース情報を返します。

Webhooks

リアルタイムのイベント通知のための Webhook サブスクリプションを管理します。セットアップ手順と署名の検証については、Webhook 機能ガイドを参照してください。

List Webhooks

http

GET /api/v1/webhooks

Scope: webhook:manage

Create Webhook

http

POST /api/v1/webhooks

Scope: webhook:manage

Body:

json

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

すべてのイベントを購読するには ["*"] を使ってください。レスポンスには署名検証のための secret（一度だけ表示）が含まれます。

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

Toggle Webhook

http

PATCH /api/v1/webhooks/{webhookId}

Scope: webhook:manage

Body:

json

{ "active": false }

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

Delete Webhook

http

DELETE /api/v1/webhooks/{webhookId}

Scope: webhook:manage

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

List Deliveries

http

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

Scope: webhook:manage

ステータスコード、レスポンスボディ、タイミングを含む、最近の配信履歴を返します。

Test Webhook

http

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

Scope: webhook:manage

Webhook の URL にテストの webhook:test イベントを送ります。

これは最近ログイン保護されたクラウドアクションです。API キーや古いブラウザセッションは 403 RECENT_LOGIN_REQUIRED を受け取ります。

Events

これらのイベントは Webhook に配信され、ライブのクラウド通知フローも駆動します。

イベント	説明
`agent:generating_started`	エージェントが応答の生成を開始した
`agent:generating_completed`	エージェントが生成を完了した（秒単位の `duration` を含む）
`agent:waiting_approval`	エージェントがユーザーの承認を待っている
`agent:error`	エージェントがエラーに遭遇した
`machine:connected`	マシンがオンラインになった
`machine:disconnected`	マシンがオフラインになった

Event Payload

json

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

典型的なフロー

最も一般的な API フローは次のとおりです:

GET /api/v1/daemons でマシンを一覧表示する
デーモンのステータスペイロードから対象のエージェントを選ぶ
POST /api/v1/shortcuts/{ideId}/chat でメッセージを送る
GET /api/v1/shortcuts/{ideId}/status をポーリングするか、Webhook を使う
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 リクエスト / 分
認証エンドポイント	10 リクエスト / 5 分
コマンドタイムアウト	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`	1 分あたりのレート制限を超過
`429`	`API_LIMIT_EXCEEDED`	月間 API 呼び出し制限に到達
`500`	—	コマンド送信に失敗（デーモンがオフライン）
`503`	—	デーモンは接続しているが WebSocket が切断されている
`504`	—	コマンド応答のタイムアウト（60 秒を超過）

REST API ​

認証 ​

スコープ ​

公開 API の構造 ​

Daemons ​

List Daemons ​

Get Daemon Status ​

Send Daemon Command ​

利用可能なコマンドタイプ ​

Execute Terminal Command ​

Disconnect Daemon ​

Revoke Daemon Token ​

Shortcuts ​

Launch IDE / CLI / ACP ​

Stop CLI / ACP ​

Send Chat Message ​

Read Chat ​

Chat Debug Bundle ​

Approve / Reject Action ​

Get Agent Status ​

Webhooks ​

List Webhooks ​

Create Webhook ​

Toggle Webhook ​

Delete Webhook ​

List Deliveries ​

Test Webhook ​

Events ​

Event Payload ​

典型的なフロー ​

このページが除外するもの ​

レート制限 ​

リクエストごとの制限 ​

月間呼び出し制限 ​

エラーコード ​

REST API

認証

スコープ

公開 API の構造

Daemons

List Daemons

Get Daemon Status

Send Daemon Command

利用可能なコマンドタイプ

Execute Terminal Command

Disconnect Daemon

Revoke Daemon Token

Shortcuts

Launch IDE / CLI / ACP

Stop CLI / ACP

Send Chat Message

Read Chat

Chat Debug Bundle

Approve / Reject Action

Get Agent Status

Webhooks

List Webhooks

Create Webhook

Toggle Webhook

Delete Webhook

List Deliveries

Test Webhook

Events

Event Payload

典型的なフロー

このページが除外するもの

レート制限

リクエストごとの制限

月間呼び出し制限

エラーコード