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
POST /api/v1/api-keys（作成）
DELETE /api/v1/api-keys/{keyId}（失効）

スコープ

スコープ	説明
`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 エージェントとともに、接続されたすべてのマシンを返します。

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:claude-cli", "type": "claude-cli", "name": "Claude Code" }
      ]
    }
  ]
}

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 セッションを開始
`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

http

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

Scope: ide:control

Body:

IDECLI

json

{ "type": "cursor" }

json

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

Stop CLI

http

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

Scope: ide:control

Body:

json

{ "type": "claude-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": "codex-cli", "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:status", "agent:approve_request"]
}

events は許可リストです — 個別に購読できるイベントと "*" でのみ受け取れるイベントについては、下記のイベントセクションを参照してください。すべてのイベントを購読するには ["*"] を使ってください。レスポンスには署名検証のための 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 を受け取ります。

TURN 資格情報

http

GET /api/v1/turn/credentials

ダッシュボード自身の P2P 接続用に、短命の TURN/STUN 資格情報を発行します（デーモンは WebSocket の auth_ok メッセージで別途資格情報を受け取ります — この REST エンドポイントはダッシュボード専用です）。認証済みリクエスト（アクセストークン）が必要です。トークンが期限切れの場合は 401 を返し、呼び出し元は STUN のみにフォールバックする必要があります。

TURN は Free を含むすべての販売プランで有効になっています — これは Free 層の制限ではなく、意図的な製品判断です。応答が STUN のみ（turn: false）にフォールバックするのは、管理者オーバーライドでプランに turnenabled: false が設定されている場合、または TURN サービス自体が未設定かエラーを返している場合のみです。

レスポンス:

json

{
  "iceServers": [ { "urls": "stun:stun.cloudflare.com:3478" } /* TURN が有効な場合は TURN サーバーも追加 */ ],
  "turn": true,
  "plan": "pro"
}

成功した TURN 資格情報はサーバー側で 1 時間キャッシュされるため、その時間内の再呼び出しは同じサーバーとともに cached: true を返します。

プロバイダーレジストリ

http

GET /api/v1/registry/providers
GET /api/v1/registry/providers/{type}
GET /api/v1/registry/providers/{type}/{version}
GET /api/v1/registry/providers/{type}/{version}/download

公開済みプロバイダーパッケージの、認証不要な公開カタログです — デーモンがプロバイダーバンドルを同期するために使用します。?channel=preview で preview 名前空間をオプトインでき、省略した場合（または他の値の場合）は stable を返します。このレジストリ配信の仕組みは、凍結されたプロバイダー閲覧用ダッシュボード UI とは別の、凍結されていない独立した機能です。

書き込みエンドポイントは、管理者、またはより狭い registry:publish スコープを持つ API キーに制限されています:

http

POST   /api/v1/registry/providers
POST   /api/v1/registry/providers/{type}/{version}/promote
DELETE /api/v1/registry/providers/{type}/{version}

POST /registry/providers は新しいパッケージを公開し、常に本文に明示的な channel: "preview" が必要です — stable への直接公開は拒否されます。stable リリースは promote エンドポイントを通じてのみ行われ、これは新しいバイトを受け付けるのではなく、既存の preview バージョンのアーティファクトを参照します。DELETE はバージョンを取り下げます（?channel=preview を指定しない限り、デフォルトは stable チャンネルです）。

Events

これらのイベントは Webhook に配信され、ライブのクラウド通知フローも駆動します。Webhook の events 購読は自由形式ではなく許可リストです（packages/server/src/utils/webhook-events.ts の normalizeWebhookEvents）:

個別に購読可能:

イベント	説明
`daemon:connect`	マシンがオンラインになった
`daemon:disconnect`	マシンがオフラインになった
`agent:status`	エージェントのステータスが変化した（スロットル済み、デーモンごとに10秒あたり最大1回）
`agent:approve_request`	予約済み — 許可リストにはあるが、サーバーは現在発行していない

発行はされるが "*" で購読した Webhook にのみ配信される:

イベント	説明
`agent:generating_started`	エージェントが応答の生成を開始した
`agent:generating_completed`	エージェントが生成を完了した（デーモンがターン開始を観測していれば整数秒の `duration` を含む）
`agent:waiting_approval`	エージェントがユーザーの承認を待っている
`agent:waiting_choice`	エージェントが複数選択のプロンプトを待っている
`agent:stopped`	エージェントセッションが停止した
`monitor:no_progress`	エージェントが進行なしで停滞しているように見える（レガシーエイリアス: `monitor:long_generating`）
`webhook:test`	`POST /webhooks/{id}/test` による明示的なテスト配信 — テスト対象の Webhook 1件にのみ配信され、購読フィルタリングをバイパスする

Event Payload

各配信は、トップレベルに event・payload・timestamp（サーバーが配信を送った時刻、エポックミリ秒）の 3 フィールドを持つ JSON 本文です。エージェント／モニターのイベント（agent:status を除く agent:* と monitor:no_progress）のペイロードは次のとおりです:

json

{
  "event": "agent:generating_completed",
  "payload": {
    "daemonId": "8e1f4c2a9b7d3e5f6a0c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
    "daemonType": "adhdev-daemon",
    "event": "agent:generating_completed",
    "timestamp": 1714000000000,
    "targetSessionId": "9b2d7c4e-1f3a-4b5c-8d6e-0a1b2c3d4e5f",
    "providerType": "claude-cli",
    "providerSessionId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
    "workspaceName": "/home/dev/projects/myproject",
    "duration": 42,
    "surfaceHidden": false,
    "muted": false
  },
  "timestamp": 1714000000215
}

フィールド	含まれる条件
`daemonId`	常に — イベントを報告したデーモン接続
`event`, `timestamp`	常に — イベント名と、デーモンがそれを観測した時刻（エポックミリ秒）
`targetSessionId`	特定のエージェントセッションに関するイベントのとき — `agent:generating_completed` と `agent:stopped` には常に含まれる
`providerType`	デーモンがセッションを解決できた場合。エージェントのプロバイダー（例: `claude-cli`、`cursor`）。解決できなければフィールドは含まれず、デーモン種別が入ることはありません
`daemonType`	常に。イベントを送信したデーモンの種別。現在は `adhdev-daemon`
`providerSessionId`	プロバイダーが独自の会話 ID を公開しているとき
`workspaceName`	セッションにワークスペースがあるとき — CLI エージェントの作業ディレクトリ、または IDE のワークスペース
`duration`	`agent:generating_completed` のみ。デーモンがターン開始を観測したとき、整数秒で
`elapsedSec`	`monitor:no_progress` — 進捗が見られなかった秒数
`modalMessage`, `modalButtons`	`agent:waiting_approval` / `agent:waiting_choice` — 承認プロンプトの文言とボタンのラベル
`surfaceHidden`, `muted`	デーモンがセッションをホストしているとき — ダッシュボードで非表示／ミュートかどうか

daemon:connect、daemon:disconnect、agent:status、webhook:test はそれぞれ別の形のペイロードを送ります。modalMessage の承認プロンプト文言を除き、ペイロードにチャットメッセージ、チャットタイトル、エージェントの応答が含まれることはありません。

典型的なフロー

最も一般的な 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 リクエスト / 分
認証ログイン/コールバックエンドポイント	100 リクエスト / 5 分
コマンドタイムアウト	60 秒

月間呼び出し制限

プラン	月間 API 呼び出し
Free	1,000
Pro	50,000
Ultra	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 ​

Stop CLI ​

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 ​

TURN 資格情報 ​

プロバイダーレジストリ ​

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

Stop CLI

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

TURN 資格情報

プロバイダーレジストリ

Events

Event Payload

典型的なフロー

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

レート制限

リクエストごとの制限

月間呼び出し制限

エラーコード