REST API

클라우드 전용

클라우드 REST API는 https://api.adhf.dev에서 제공됩니다. 셀프호스트 사용자는 로컬 API에 접근할 수 있습니다 — Self-hosted API를 참고하세요.

이 페이지는 호스팅 클라우드 자동화 표면을 문서화합니다.

다음은 다루지 않습니다:

/api/v1/status 같은 로컬 스탠드얼론 엔드포인트
세션-호스트 복구 같은 셀프호스트 런타임 오퍼레이터 흐름
/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`	전달 내역 조회 및 최근 대시보드 로그인 시 웹훅 관리

공개 API 구조

대부분의 클라우드 통합에서는 다음 레이어로 생각하세요:

GET /api/v1/daemons — 연결된 머신 찾기
GET /api/v1/daemons/{daemonId}/status — 머신 및 세션 상태 검사
/api/v1/shortcuts/* — 실제로 필요한 일반적인 에이전트 액션
/api/v1/webhooks/* — 자체 시스템으로 이벤트 전달

원시 데몬 명령 라우터가 특별히 필요하지 않으면 Shortcuts를 선호하세요.

모든 데몬 및 Shortcut 경로는 인증된 클라우드 계정이 소유한 머신과 세션으로 범위가 한정됩니다. 다른 계정의 데몬이나 합성 세션 ID를 제공하면 계정 경계를 넘는 대신 404를 반환합니다.

데몬

연결된 머신(데몬)과 해당 IDE를 관리합니다.

데몬 목록 조회

http

GET /api/v1/daemons

스코프: ide:read

관리되는 IDE, CLI 에이전트와 함께 연결된 모든 머신을 반환합니다.

응답:

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" }
      ]
    }
  ]
}

데몬 상태 조회

http

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

스코프: ide:read

IDE/CLI 상태, 워크스페이스 정보, 에이전트 활동을 포함한 상세 데몬 상태를 반환합니다.

데몬 명령 전송

http

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

스코프: ide:control

대상 머신에 직접 명령을 전송합니다.

대부분의 통합에서는 아래의 Shortcuts API를 선호하세요. POST /daemons/:id/command는 하위 레벨 탈출구입니다.

본문:

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`	데몬	`ideType, enableCdp?`	IDE 실행
`launch_cli`	데몬	`cliType, dir?, model?`	CLI 세션 시작
`stop_cli`	데몬	`cliType`	CLI 세션 중지

내부 라우터의 모든 명령이 공개 자동화 자료에 포함되는 것은 아닙니다. 일반 통합을 구축 중이라면 문서화된 명령 세트나 Shortcut 엔드포인트를 사용하세요.

터미널 명령 실행

http

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

스코프: terminal:exec

데몬 머신에서 터미널 명령을 실행합니다.

본문:

json

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

데몬 연결 해제

http

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

스코프: ide:control

데몬을 강제로 연결 해제합니다. 데몬은 자동으로 재연결할 수 있습니다.

최근 로그인 보호 클라우드 액션입니다. API 키와 오래된 브라우저 세션은 403 RECENT_LOGIN_REQUIRED를 받습니다.

데몬 토큰 취소

http

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

스코프: ide:control

데몬의 연결 토큰을 영구적으로 취소합니다. 머신에서 adhdev setup을 다시 실행해야 합니다.

최근 로그인 보호 클라우드 액션입니다. API 키와 오래된 브라우저 세션은 403 RECENT_LOGIN_REQUIRED를 받습니다.

Shortcuts

가장 일반적인 에이전트 액션을 위한 편의 엔드포인트.

IDE / CLI 실행

http

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

스코프: ide:control

본문:

IDECLI

json

{ "type": "cursor" }

json

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

CLI 중지

http

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

스코프: ide:control

본문:

json

{ "type": "claude-cli" }

채팅 메시지 전송

http

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

스코프: agent:control

AI 에이전트에 메시지를 전송합니다. ideId는 데몬/세션 상태 API가 반환한 머신 범위 대상 ID로, {daemonId}:session:{sessionId} 같은 합성 세션 경로도 포함됩니다.

외부 자동화의 기본 전송 경로입니다.

본문 (레거시 텍스트 형식):

json

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

본문 (표준 엔벨로프 형식):

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 중 하나를 제공해야 합니다.

채팅 읽기

http

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

스코프: agent:read

에이전트의 현재 채팅 내용을 읽습니다. ?agentType=cursor로 필터링 가능합니다.

채팅 디버그 번들

http

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

스코프: agent:read

현재 채팅/세션에 대한 경계가 있는 정제된 디버그 번들을 빌드합니다. 데몬이 권위 있는 프로바이더/파서/세션/터미널 증거를 생성하며, POST는 현재 렌더링된 프론트엔드 상태를 보완하는 대시보드 frontendSnapshot을 포함할 수 있습니다.

POST 선택 본문:

json

{ "agentType": "codex-cli", "frontendSnapshot": { "activeConversation": { "sessionId": "session_..." } } }

응답에는 bundle과 복사 가능한 text가 포함됩니다. 비밀번호와 자격 증명은 기본적으로 편집됩니다.

액션 승인 / 거부

http

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

스코프: agent:control

보류 중인 에이전트 액션을 승인하거나 거부합니다.

본문:

json

{ "action": "approve" }

또는

json

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

에이전트 상태 조회

http

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

스코프: agent:read

현재 상태(idle, generating, waiting_approval, error), 프로바이더가 있는 경우 요약 메타데이터/컨트롤, 워크스페이스 정보를 반환합니다.

웹훅

실시간 이벤트 알림을 위한 웹훅 구독을 관리합니다. 설정 지침과 서명 검증은 웹훅 기능 가이드를 참고하세요.

웹훅 목록 조회

http

GET /api/v1/webhooks

스코프: webhook:manage

웹훅 생성

http

POST /api/v1/webhooks

스코프: webhook:manage

본문:

json

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

events는 허용 목록입니다 — 개별 구독 가능한 이벤트와 "*"로만 받을 수 있는 이벤트는 아래 이벤트 섹션을 참고하세요. ["*"]를 사용하면 모든 이벤트를 구독합니다. 응답에는 서명 검증을 위한 secret(한 번만 표시됨)이 포함됩니다.

최근 로그인 보호 클라우드 액션입니다. API 키와 오래된 브라우저 세션은 403 RECENT_LOGIN_REQUIRED를 받습니다.

웹훅 토글

http

PATCH /api/v1/webhooks/{webhookId}

스코프: webhook:manage

본문:

json

{ "active": false }

최근 로그인 보호 클라우드 액션입니다. API 키와 오래된 브라우저 세션은 403 RECENT_LOGIN_REQUIRED를 받습니다.

웹훅 삭제

http

DELETE /api/v1/webhooks/{webhookId}

스코프: webhook:manage

최근 로그인 보호 클라우드 액션입니다. API 키와 오래된 브라우저 세션은 403 RECENT_LOGIN_REQUIRED를 받습니다.

전달 목록 조회

http

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

스코프: webhook:manage

상태 코드, 응답 본문, 타이밍이 포함된 최근 전달 히스토리를 반환합니다.

웹훅 테스트

http

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

스코프: webhook:manage

웹훅 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 구독은 자유 목록이 아닌 허용 목록입니다(packages/server/src/utils/webhook-events.ts의 normalizeWebhookEvents):

개별 구독 가능:

이벤트	설명
`daemon:connect`	머신이 온라인
`daemon:disconnect`	머신이 오프라인
`agent:status`	에이전트 상태 변경(스로틀됨, 데몬당 10초에 최대 1회)
`agent:approve_request`	예약됨 — 허용 목록에는 있지만 서버가 현재 발행하지 않음

발행되지만 "*"로 구독한 웹훅에만 전달됨:

이벤트	설명
`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`를 통한 명시적 테스트 전달 — 테스트 대상 웹훅 하나에만 전달되며 구독 필터링을 우회함

이벤트 페이로드

모든 전송은 최상위 필드 세 개 — event, payload, timestamp(서버가 전송한 시각, epoch 밀리초) — 로 이루어진 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`	항상 — 이벤트 이름과 데몬이 관측한 시각(epoch 밀리초)
`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 폴링 또는 웹훅 사용
GET /api/v1/shortcuts/{ideId}/chat으로 트랜스크립트 읽기

이 페이지에서 제외된 항목

다음 중 하나를 찾고 있다면 잘못된 API 페이지입니다:

스탠드얼론 GET /api/v1/status
스탠드얼론 POST /api/v1/command
호스팅 로컬 CLI 세션의 런타임 스냅샷/이벤트 엔드포인트
터미널 mux 워크스페이스 엔드포인트

이들은 Self-hosted API에 속합니다.

속도 제한

요청별 제한

제한	값
API 키	분당 120 요청
IP 주소	분당 60 요청
인증 로그인/콜백 엔드포인트	5분당 100 요청
명령 타임아웃	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`	분당 속도 제한 초과
`429`	`API_LIMIT_EXCEEDED`	월별 API 호출 제한 도달
`500`	—	명령 전송 실패 (데몬 오프라인)
`503`	—	데몬이 연결되어 있지만 WebSocket 연결 끊김
`504`	—	명령 응답 타임아웃 (60초 초과)

REST API ​

인증 ​

스코프 ​

공개 API 구조 ​

데몬 ​

데몬 목록 조회 ​

데몬 상태 조회 ​

데몬 명령 전송 ​

사용 가능한 명령 유형 ​

터미널 명령 실행 ​

데몬 연결 해제 ​

데몬 토큰 취소 ​

Shortcuts ​

IDE / CLI 실행 ​

CLI 중지 ​

채팅 메시지 전송 ​

채팅 읽기 ​

채팅 디버그 번들 ​

액션 승인 / 거부 ​

에이전트 상태 조회 ​

웹훅 ​

웹훅 목록 조회 ​

웹훅 생성 ​

웹훅 토글 ​

웹훅 삭제 ​

전달 목록 조회 ​

웹훅 테스트 ​

TURN 자격 증명 ​

프로바이더 레지스트리 ​

이벤트 ​

이벤트 페이로드 ​

일반적인 흐름 ​

이 페이지에서 제외된 항목 ​

속도 제한 ​

요청별 제한 ​

월별 호출 제한 ​

에러 코드 ​

REST API

인증

스코프

공개 API 구조

데몬

데몬 목록 조회

데몬 상태 조회

데몬 명령 전송

사용 가능한 명령 유형

터미널 명령 실행

데몬 연결 해제

데몬 토큰 취소

Shortcuts

IDE / CLI 실행

CLI 중지

채팅 메시지 전송

채팅 읽기

채팅 디버그 번들

액션 승인 / 거부

에이전트 상태 조회

웹훅

웹훅 목록 조회

웹훅 생성

웹훅 토글

웹훅 삭제

전달 목록 조회

웹훅 테스트

TURN 자격 증명

프로바이더 레지스트리

이벤트

이벤트 페이로드

일반적인 흐름

이 페이지에서 제외된 항목

속도 제한

요청별 제한

월별 호출 제한

에러 코드