## Panorama: qué habilita el API

La superficie del agent integra herramientas automáticas en la misma capa de visibilidad que las personas en Dailybot.

| Capacidad | Propósito |
| --- | --- |
| **Reportes del agent** | Enviar avance legible (qué cambió, por qué importa) más datos estructurados opcionales para timelines y resúmenes. |
| **Monitoreo de salud** | Emitir heartbeats y metadata de sesión para que ops vea estados activo, inactivo, estancado o error. |
| **Mensajería del inbox** | Traer instrucciones en cola de humanos para que el agent reciba tareas y contexto en el próximo check-in. |

El reporteo suele ser **push** (agent hacia Dailybot). El inbox suele ser **pull** (el agent pregunta qué hay pendiente). La salud puede ser push o consulta según tu integración.

## Autenticación

| Método | Cuándo usarlo |
| --- | --- |
| **Sesión del CLI** | Desarrollo local e interactivo: ejecuta `dailybot login` una vez por entorno. |
| **API key** | CI, devcontainers y agents sin UI: define `DAILYBOT_API_KEY` en el entorno; el CLI y clientes HTTP la leen. |
| **Variables de entorno** | Combina keys con `DAILYBOT_PROJECT_NAME` (o resolución equivalente del proyecto) para que reportes y estado caigan en el workspace correcto. |

Trata las keys como contraseñas: alcance mínimo al workspace, rotación si hay compromiso e inyección vía el almacén de secretos de tu plataforma—nunca en el repo.

## Endpoints centrales (conceptuales)

**Envío de reporte** — Conceptualmente un **POST** que acepta:

- `message` (obligatorio): texto corto estilo standup.
- `metadata` (opcional): JSON de contexto (por ejemplo `model`, `repo`, `branch`, `plan`).
- Payload estructurado (opcional): arreglos JSON como `completed`, `in_progress`, `blockers`.
- Flag `milestone` (opcional): marca hitos grandes para resaltar aguas abajo.

**Estado / salud del agent** — Heartbeats y IDs de sesión vinculan la corrida al dashboard; los payloads suelen traer tiempos, nombre de agent o proyecto e identidad para correlacionar reportes.

**Inbox del agent** — Conceptualmente un **GET** (u operación de listado) acotado por workspace e identidad del agent, devolviendo instrucciones pendientes ordenadas. El agent las fusiona en el plan siguiente antes o durante la ejecución.

Las rutas URL exactas y los schemas aparecen en el CLI oficial y la documentación; preferí esas fuentes al generar código cliente.

## Formatos de respuesta y errores

Las llamadas exitosas devuelven cuerpos **JSON** (o código de salida `0` del CLI con confirmación en stdout). Categorías típicas de error:

| Categoría | Significado | Acción típica |
| --- | --- | --- |
| `401` / auth | Credenciales inválidas o ausentes | Corrige `DAILYBOT_API_KEY` o renueva el login del CLI. |
| `400` / validación | JSON mal formado o campos obligatorios faltantes | Valida longitud del mensaje y forma del JSON antes de reintentar. |
| `429` / rate limit | Demasiadas peticiones en una ventana | Haz backoff exponencial; agrupa actualizaciones con sentido. |
| `5xx` / servidor | Falla transitoria | Reintenta con jitter; no hagas bucles ajustados. |

Parsea los cuerpos de error cuando existan; el CLI muestra stderr legible para las mismas condiciones.

## Límites de tasa y buenas prácticas

- Prefiere **pocos reportes sustantivos** a spam por commit.
- Incluye **`model` en metadata** cuando el entorno no lo setea solo.
- Usa **timeouts y wrappers no bloqueantes** en el loop del agent.
- Ante fallo, **registra y continúa** para telemetría no crítica; reintenta solo envíos idempotentes.

## CLI frente a HTTP directo

El **Dailybot CLI** es el contrato recomendado para la mayoría de equipos: maneja refresco de auth, resolución de proyecto y mapeo de argumentos al **HTTP** API subyacente.

| Enfoque | Ideal para |
| --- | --- |
| **CLI** (comandos `dailybot`, scripts wrapper) | Setups estándar de agent, adopción rápida, flags consistentes. |
| **HTTP directo** | Servicios propios, lenguajes sin CLI, o control fino de headers y reintentos—mismas reglas de auth. |

Lo que el CLI envía se puede reproducir con **HTTP** **POST**/ **GET** y headers **Bearer** o de key una vez reflejes la forma oficial de la petición.

## Soporte de webhook

Para entrega **push** (por ejemplo avisar a un sistema externo cuando llega un reporte o cambia el inbox), configura URLs **webhook** en ajustes del workspace donde el producto lo exponga. Los **webhooks** complementan el API: son callbacks de evento, no reemplazo de las llamadas autenticadas del agent.

Usa **webhooks** cuando la automatización aguas abajo deba reaccionar sin polling; conserva **HMAC** o secretos de firma si el producto los ofrece, y responde `2xx` rápido mientras procesas trabajo en segundo plano.

---

Para el spec de campo y ejemplos actuales, consulta la documentación para developers de Dailybot y la ayuda del CLI.

## FAQ

**¿Qué cubre el agent API de Dailybot?**  Cubre reportes salientes del agent (mensajes estilo standup con JSON estructurado y metadata opcionales), señales de estado y salud del agent (heartbeats y contexto de sesión) y el inbox del agent para traer instrucciones humanas pendientes. Juntos permiten integrar agentes con Dailybot para visibilidad y coordinación en dos direcciones.

**¿Cómo me autentico al agent API?**  Usa la sesión del Dailybot CLI después de dailybot login, o define DAILYBOT_API_KEY en entornos no interactivos. El CLI lee tu identidad del workspace desde esa sesión o esa key. Los tokens estilo Bearer mapean a la misma cuenta; nunca subas keys a git—usa secretos de CI o archivos de entorno locales.

**¿Cuáles son los principales endpoints conceptuales?**  Piensa en tres grupos: envío de reportes (estilo POST: mensaje más metadata, json-data y flag milestone opcionales), salud o estado del agent (heartbeat e info de sesión para que el dashboard sea preciso) y lectura del inbox (estilo GET de instrucciones en cola para la próxima corrida del agent). Las rutas y campos exactos siguen el contrato actual del producto; el CLI los envuelve para la mayoría de equipos.