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
POST /api/v1/api-keys (crear)
DELETE /api/v1/api-keys/{keyId} (revocar)

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

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
`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

http

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

Alcance: ide:control

Cuerpo:

IDECLI

json

{ "type": "cursor" }

json

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

Detener CLI

http

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

Alcance: ide:control

Cuerpo:

json

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

events es una lista de permitidos — consulta la sección Eventos más abajo para ver qué nombres se pueden suscribir individualmente frente a los que solo llegan vía "*". 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.

Credenciales TURN

http

GET /api/v1/turn/credentials

Emite credenciales TURN/STUN de corta duración para la propia conexión P2P del panel (un daemon recibe sus credenciales por separado, en el mensaje WebSocket auth_ok — este endpoint REST es solo para el panel). Requiere una solicitud autenticada (token de acceso); un token caducado devuelve 401 y quien llama debe recurrir solo a STUN.

TURN está habilitado en todos los planes de venta, incluido Free — esta es una decisión de producto deliberada, no una restricción del nivel Free. La respuesta solo recurre a STUN únicamente (turn: false) cuando a un plan se le ha dado turnenabled: false mediante una anulación de administrador, o cuando el propio servicio TURN no está configurado o devuelve un error.

Respuesta:

json

{
  "iceServers": [ { "urls": "stun:stun.cloudflare.com:3478" } /* + servidores TURN cuando está habilitado */ ],
  "turn": true,
  "plan": "pro"
}

Las credenciales TURN exitosas se almacenan en caché del lado del servidor durante 1 hora, así que las llamadas repetidas dentro de esa ventana devuelven cached: true con los mismos servidores.

Registro de Proveedores

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

Catálogo público y sin autenticación de paquetes de proveedores publicados — los daemons lo usan para sincronizar los paquetes de proveedores. ?channel=preview habilita el espacio de nombres preview; omitirlo (o cualquier otro valor) devuelve stable. Este mecanismo de entrega del registro es una capacidad distinta y no congelada, separada de la interfaz del panel para explorar proveedores, que sí está congelada.

Los endpoints de escritura están restringidos a administradores o a una clave de API con el alcance más restringido registry:publish:

http

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

POST /registry/providers publica un nuevo paquete y siempre requiere un channel: "preview" explícito en el cuerpo — publicar directamente en stable se rechaza; un lanzamiento a stable solo ocurre a través del endpoint promote, que hace referencia al artefacto de la versión preview existente en lugar de aceptar bytes nuevos. DELETE retira una versión (por defecto el canal stable a menos que se indique ?channel=preview).

Eventos

Estos eventos se entregan a los webhooks y también impulsan los flujos de notificación de la nube en vivo. Las suscripciones events de webhook son una lista de permitidos, no una lista libre (normalizeWebhookEvents en packages/server/src/utils/webhook-events.ts):

Suscribibles individualmente:

Evento	Descripción
`daemon:connect`	La máquina se conectó
`daemon:disconnect`	La máquina se desconectó
`agent:status`	Cambió el estado del agente (limitado, máx. 1 cada 10s por daemon)
`agent:approve_request`	Reservado — está en la lista de permitidos pero el servidor no lo despacha actualmente

Despachados pero solo entregados a webhooks suscritos con "*":

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 enteros cuando el daemon vio empezar el turno)
`agent:waiting_approval`	El agente está esperando la aprobación del usuario
`agent:waiting_choice`	El agente está esperando una selección múltiple
`agent:stopped`	La sesión del agente se detuvo
`monitor:no_progress`	El agente parece estancado sin progreso (alias legado: `monitor:long_generating`)
`webhook:test`	Entrega de prueba explícita vía `POST /webhooks/{id}/test` — se entrega solo al webhook que se está probando y omite el filtrado de suscripción

Carga útil del evento

Cada entrega es un cuerpo JSON con tres campos de nivel superior: event, payload y timestamp (cuándo envió el servidor la entrega, en milisegundos epoch). Para los eventos de agente y de monitor (agent:* salvo agent:status, y monitor:no_progress) la carga útil tiene este aspecto:

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
}

Campo	Cuándo aparece
`daemonId`	Siempre: la conexión del daemon que informó del evento
`event`, `timestamp`	Siempre: el nombre del evento y cuándo lo observó el daemon (milisegundos epoch)
`targetSessionId`	Cuando el evento se refiere a una sesión de agente concreta; siempre en `agent:generating_completed` y `agent:stopped`
`providerType`	Cuando el daemon puede resolver la sesión. El proveedor del agente, por ejemplo `claude-cli` o `cursor`. Si no, el campo no aparece; nunca contiene el tipo de daemon
`daemonType`	Siempre. El tipo de daemon que envió el evento, actualmente `adhdev-daemon`
`providerSessionId`	Cuando el proveedor expone su propio id de conversación
`workspaceName`	Cuando la sesión tiene un espacio de trabajo: el directorio de trabajo de un agente CLI o el espacio de trabajo del IDE
`duration`	Solo en `agent:generating_completed`, en segundos enteros, cuando el daemon vio empezar el turno
`elapsedSec`	`monitor:no_progress`: segundos sin progreso visible
`modalMessage`, `modalButtons`	`agent:waiting_approval` / `agent:waiting_choice`: el texto de la solicitud de aprobación y las etiquetas de sus botones
`surfaceHidden`, `muted`	Cuando el daemon aloja la sesión: si está oculta o silenciada en el panel

daemon:connect, daemon:disconnect, agent:status y webhook:test envían cargas útiles propias con otra forma. Aparte del texto de la solicitud de aprobación en modalMessage, la carga útil nunca incluye mensajes de chat, títulos de chat ni respuestas del agente.

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 login/callback de autenticación	100 solicitudes / 5 minutos
Timeout de comando	60 segundos

Límites de llamadas mensuales

Plan	Llamadas de API mensuales
Free	1,000
Pro	50,000
Ultra	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 ​

Detener CLI ​

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 ​

Credenciales TURN ​

Registro de Proveedores ​

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

Detener CLI

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

Credenciales TURN

Registro de Proveedores

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