REST API

Solo en la nube

La REST API de la nube está disponible en https://api.adhf.dev. Los usuarios autoalojados pueden acceder a una API local — consulta API autoalojada.

Esta página documenta la superficie de automatización de la nube alojada.

No intenta cubrir:

endpoints standalone locales como /api/v1/status
flujos de operador de runtime autoalojado como la recuperación de session-host
endpoints locales de terminal mux como /api/v1/mux/*

Para esos, usa la documentación de OSS autoalojado en su lugar.

Autenticación

Todas las solicitudes de la API requieren una clave de API en el encabezado Authorization:

bash

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

Nota: La emisión de claves de API a través del panel no está disponible en la versión actual. Las claves existentes siguen funcionando. Contacta con soporte si necesitas acceso.

Para la automatización normal de la nube, las claves de API son la superficie de autenticación principal.

Algunas mutaciones sensibles de la cuenta de la nube ahora requieren un inicio de sesión reciente en el navegador en lugar de autenticación por clave de API. Esas rutas esperan una sesión JWT de panel nueva y devuelven 403 RECENT_LOGIN_REQUIRED cuando se llaman con una clave de API o una sesión obsoleta.

Rutas actuales protegidas por inicio de sesión reciente:

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

Alcances

Alcance	Descripción
`ide:read`	Listar daemons, leer el estado del IDE
`ide:control`	Lanzar/detener IDEs, enviar comandos de daemon
`agent:read`	Leer mensajes de chat, estado del agente
`agent:control`	Enviar mensajes, aprobar/rechazar acciones
`terminal:exec`	Ejecutar comandos de terminal en las máquinas
`webhook:manage`	Inspeccionar entregas y, con un inicio de sesión de panel reciente, gestionar webhooks

Forma de la API pública

Para la mayoría de las integraciones de la nube, piensa en estas capas:

GET /api/v1/daemons para encontrar máquinas conectadas
GET /api/v1/daemons/{daemonId}/status para inspeccionar el estado de la máquina y la sesión
/api/v1/shortcuts/* para las acciones de agente comunes que realmente quieres
/api/v1/webhooks/* para la entrega de eventos a tus propios sistemas

Prefiere Shortcuts a menos que necesites específicamente el enrutador de comandos de daemon en bruto.

Todas las rutas de daemon y shortcut tienen alcance limitado a las máquinas y sesiones que posee la cuenta de la nube autenticada. Suministrar el daemon o el id de sesión sintético de otra cuenta devuelve 404 en lugar de cruzar los límites de la cuenta.

Daemons

Gestiona las máquinas conectadas (daemons) y sus IDEs.

Listar daemons

http

GET /api/v1/daemons

Alcance: ide:read

Devuelve todas las máquinas conectadas con sus IDEs, CLIs y agentes ACP gestionados.

Respuesta:

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

Obtener el estado del daemon

http

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

Alcance: ide:read

Devuelve el estado detallado del daemon incluyendo el estado del IDE/CLI, la info del workspace y la actividad del agente.

Enviar comando de daemon

http

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

Alcance: ide:control

Envía un comando directo a la máquina de destino.

Para la mayoría de las integraciones, prefiere la API de Shortcuts de abajo. POST /daemons/:id/command es la escotilla de escape de más bajo nivel.

Cuerpo:

json

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

Tipos de comando disponibles

Comando	Objetivo	Carga útil	Descripción
`send_chat`	IDE/CLI	`message`	Enviar un mensaje de chat
`read_chat`	IDE/CLI	—	Leer el contenido actual del chat
`resolve_action`	IDE/CLI	`action`	Aprobar/rechazar una acción del agente
`screenshot`	IDE	`width?`	Tomar una captura de pantalla
`launch_ide`	Daemon	`ideType, enableCdp?`	Lanzar un IDE
`launch_cli`	Daemon	`cliType, dir?, model?`	Iniciar una sesión CLI/ACP
`stop_cli`	Daemon	`cliType`	Detener una sesión CLI

No todos los comandos del enrutador interno pertenecen al material de automatización pública. Si estás construyendo una integración normal, mantente en el conjunto de comandos documentado o en los endpoints de shortcut.

Ejecutar comando de terminal

http

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

Alcance: terminal:exec

Ejecuta un comando de terminal en la máquina del daemon.

Cuerpo:

json

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

Desconectar daemon

http

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

Alcance: ide:control

Fuerza la desconexión del daemon. El daemon puede reconectarse automáticamente.

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Revocar el token del daemon

http

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

Alcance: ide:control

Revoca el token de conexión del daemon permanentemente. Requiere ejecutar adhdev setup de nuevo en la máquina.

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Shortcuts

Endpoints de conveniencia para las acciones de agente más comunes.

Lanzar IDE / CLI / ACP

http

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

Alcance: ide:control

Cuerpo:

IDECLIACP

json

{ "type": "cursor" }

json

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

json

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

Detener CLI / ACP

http

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

Alcance: ide:control

Cuerpo:

json

{ "type": "gemini-cli" }

Enviar mensaje de chat

http

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

Alcance: agent:control

Envía un mensaje a un agente de IA. El ideId es el ID de destino con alcance de máquina devuelto por las APIs de estado de daemon/sesión, incluyendo rutas de sesión sintéticas como {daemonId}:session:{sessionId}.

Esta es la ruta de envío predeterminada para la automatización externa.

Cuerpo (forma de texto heredada):

json

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

Cuerpo (forma de envoltura canónica):

json

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

Opcional — especifica el tipo de agente para IDEs multiagente:

json

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

Debes proporcionar message o input.

Leer chat

http

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

Alcance: agent:read

Lee el contenido actual del chat de un agente. Opcionalmente filtra por ?agentType=cursor.

Paquete de depuración de chat

http

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

Alcance: agent:read

Construye un paquete de depuración acotado y saneado para el chat/sesión actual. El daemon genera la evidencia autoritativa de proveedor/parser/sesión/terminal; POST puede incluir un frontendSnapshot del panel para complementarlo con el estado del frontend actualmente renderizado.

Cuerpo opcional para POST:

json

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

La respuesta incluye bundle y text listo para copiar. Los secretos y credenciales se redactan por defecto.

Aprobar / Rechazar acción

http

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

Alcance: agent:control

Aprueba o rechaza una acción de agente pendiente.

Cuerpo:

json

{ "action": "approve" }

json

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

Obtener el estado del agente

http

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

Alcance: agent:read

Devuelve el estado actual (idle, generating, waiting_approval, error), los metadatos/controles del resumen del proveedor cuando están presentes, y la info del workspace.

Webhooks

Gestiona las suscripciones de webhook para notificaciones de eventos en tiempo real. Consulta la guía de la función de webhooks para las instrucciones de configuración y la verificación de firma.

Listar webhooks

http

GET /api/v1/webhooks

Alcance: webhook:manage

Crear webhook

http

POST /api/v1/webhooks

Alcance: webhook:manage

Cuerpo:

json

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

Usa ["*"] para suscribirte a todos los eventos. La respuesta incluye un secret (mostrado solo una vez) para la verificación de firma.

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Alternar webhook

http

PATCH /api/v1/webhooks/{webhookId}

Alcance: webhook:manage

Cuerpo:

json

{ "active": false }

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Eliminar webhook

http

DELETE /api/v1/webhooks/{webhookId}

Alcance: webhook:manage

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Listar entregas

http

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

Alcance: webhook:manage

Devuelve el historial de entregas reciente con códigos de estado, cuerpos de respuesta y timing.

Probar webhook

http

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

Alcance: webhook:manage

Envía un evento de prueba webhook:test a la URL del webhook.

Esta es una acción de la nube protegida por inicio de sesión reciente. Las claves de API y las sesiones de navegador obsoletas reciben 403 RECENT_LOGIN_REQUIRED.

Eventos

Estos eventos se entregan a los webhooks y también impulsan los flujos de notificación de la nube en vivo.

Evento	Descripción
`agent:generating_started`	El agente empezó a generar una respuesta
`agent:generating_completed`	El agente terminó de generar (incluye `duration` en segundos)
`agent:waiting_approval`	El agente está esperando la aprobación del usuario
`agent:error`	El agente encontró un error
`machine:connected`	La máquina se conectó
`machine:disconnected`	La máquina se desconectó

Carga útil del evento

json

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

Flujo típico

El flujo de API más común es:

Listar máquinas con GET /api/v1/daemons
Elegir un agente de destino de la carga útil de estado del daemon
Enviar un mensaje con POST /api/v1/shortcuts/{ideId}/chat
Sondear GET /api/v1/shortcuts/{ideId}/status o usar webhooks
Leer la transcripción con GET /api/v1/shortcuts/{ideId}/chat

Lo que esta página excluye

Si estás buscando alguno de estos, esta es la página de API equivocada:

standalone GET /api/v1/status
standalone POST /api/v1/command
endpoints de snapshot/eventos de runtime para sesiones CLI locales alojadas
endpoints de workspace de terminal mux

Esos pertenecen a la API autoalojada.

Límites de tasa

Límites por solicitud

Límite	Valor
Clave de API	120 solicitudes / minuto
Dirección IP	60 solicitudes / minuto
Endpoints de autenticación	10 solicitudes / 5 minutos
Timeout de comando	60 segundos

Límites de llamadas mensuales

Plan	Llamadas de API mensuales
Free	1,000
Pro	50,000
Team	500,000
Enterprise	Ilimitado

Códigos de error

Estado	Código	Descripción
`400`	—	Solicitud incorrecta (la validación falló)
`401`	`AUTH_REQUIRED`	Falta el encabezado `Authorization`
`401`	`AUTH_INVALID`	Clave de API inválida o expirada
`403`	`AUTH_FORBIDDEN`	La clave de API carece del alcance requerido
`403`	`RECENT_LOGIN_REQUIRED`	Una acción sensible de la nube requiere un inicio de sesión de panel nuevo en lugar de autenticación por clave de API o una sesión obsoleta
`404`	—	Daemon/recurso no encontrado, invitación/compartir expirada, u objetivo no propiedad de la cuenta autenticada
`429`	`RATE_LIMITED`	Límite de tasa por minuto excedido
`429`	`API_LIMIT_EXCEEDED`	Límite de llamadas de API mensual alcanzado
`500`	—	Fallo al enviar el comando (daemon offline)
`503`	—	Daemon conectado pero WebSocket desconectado
`504`	—	Timeout de respuesta de comando (excedió 60s)

REST API ​

Autenticación ​

Alcances ​

Forma de la API pública ​

Daemons ​

Listar daemons ​

Obtener el estado del daemon ​

Enviar comando de daemon ​

Tipos de comando disponibles ​

Ejecutar comando de terminal ​

Desconectar daemon ​

Revocar el token del daemon ​

Shortcuts ​

Lanzar IDE / CLI / ACP ​

Detener CLI / ACP ​

Enviar mensaje de chat ​

Leer chat ​

Paquete de depuración de chat ​

Aprobar / Rechazar acción ​

Obtener el estado del agente ​

Webhooks ​

Listar webhooks ​

Crear webhook ​

Alternar webhook ​

Eliminar webhook ​

Listar entregas ​

Probar webhook ​

Eventos ​

Carga útil del evento ​

Flujo típico ​

Lo que esta página excluye ​

Límites de tasa ​

Límites por solicitud ​

Límites de llamadas mensuales ​

Códigos de error ​

REST API

Autenticación

Alcances

Forma de la API pública

Daemons

Listar daemons

Obtener el estado del daemon

Enviar comando de daemon

Tipos de comando disponibles

Ejecutar comando de terminal

Desconectar daemon

Revocar el token del daemon

Shortcuts

Lanzar IDE / CLI / ACP

Detener CLI / ACP

Enviar mensaje de chat

Leer chat

Paquete de depuración de chat

Aprobar / Rechazar acción

Obtener el estado del agente

Webhooks

Listar webhooks

Crear webhook

Alternar webhook

Eliminar webhook

Listar entregas

Probar webhook

Eventos

Carga útil del evento

Flujo típico

Lo que esta página excluye

Límites de tasa

Límites por solicitud

Límites de llamadas mensuales

Códigos de error