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

스코프

스코프	설명
`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, ACP 에이전트와 함께 연결된 모든 머신을 반환합니다.

응답:

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

데몬 상태 조회

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/ACP 세션 시작
`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 / ACP 실행

http

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

스코프: ide:control

본문:

IDECLIACP

json

{ "type": "cursor" }

json

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

json

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

CLI / ACP 중지

http

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

스코프: ide:control

본문:

json

{ "type": "gemini-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": "hermes", "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:generating_completed", "agent:waiting_approval"]
}

["*"]를 사용하면 모든 이벤트를 구독합니다. 응답에는 서명 검증을 위한 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를 받습니다.

이벤트

이 이벤트는 웹훅으로 전달되며 실시간 클라우드 알림 흐름도 구동합니다.

이벤트	설명
`agent:generating_started`	에이전트가 응답 생성 시작
`agent:generating_completed`	에이전트가 생성 완료 (`duration`이 초 단위로 포함)
`agent:waiting_approval`	에이전트가 사용자 승인 대기 중
`agent:error`	에이전트에서 오류 발생
`machine:connected`	머신이 온라인
`machine:disconnected`	머신이 오프라인

이벤트 페이로드

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 폴링 또는 웹훅 사용
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분당 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초 초과)

REST API ​

인증 ​

스코프 ​

공개 API 구조 ​

데몬 ​

데몬 목록 조회 ​

데몬 상태 조회 ​

데몬 명령 전송 ​

사용 가능한 명령 유형 ​

터미널 명령 실행 ​

데몬 연결 해제 ​

데몬 토큰 취소 ​

Shortcuts ​

IDE / CLI / ACP 실행 ​

CLI / ACP 중지 ​

채팅 메시지 전송 ​

채팅 읽기 ​

채팅 디버그 번들 ​

액션 승인 / 거부 ​

에이전트 상태 조회 ​

웹훅 ​

웹훅 목록 조회 ​

웹훅 생성 ​

웹훅 토글 ​

웹훅 삭제 ​

전달 목록 조회 ​

웹훅 테스트 ​

이벤트 ​

이벤트 페이로드 ​

일반적인 흐름 ​

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

속도 제한 ​

요청별 제한 ​

월별 호출 제한 ​

에러 코드 ​

REST API

인증

스코프

공개 API 구조

데몬

데몬 목록 조회

데몬 상태 조회

데몬 명령 전송

사용 가능한 명령 유형

터미널 명령 실행

데몬 연결 해제

데몬 토큰 취소

Shortcuts

IDE / CLI / ACP 실행

CLI / ACP 중지

채팅 메시지 전송

채팅 읽기

채팅 디버그 번들

액션 승인 / 거부

에이전트 상태 조회

웹훅

웹훅 목록 조회

웹훅 생성

웹훅 토글

웹훅 삭제

전달 목록 조회

웹훅 테스트

이벤트

이벤트 페이로드

일반적인 흐름

이 페이지에서 제외된 항목

속도 제한

요청별 제한

월별 호출 제한

에러 코드