Para Builders

API REST

La API REST es la puerta principal para integrar Daguito en tu código. Te autenticas con un token Bearer y, según la credencial que uses, puedes desplegar flujos de forma idempotente, alimentar y consultar bases de conocimiento, y leer la analítica de uso de tu organización. Esta pagina documenta solo los endpoints publicos y verificados.

URL base y autenticación

Todas las llamadas van contra un único endpoint de producción:

https://api.daguito.com

Cada petición se autentica con un token Bearer en la cabecera Authorization:

Authorization: Bearer <credencial>

Existen tres tipos de credencial, cada una con su propio prefijo:

• dgsk_acc_ — clave de cuenta, con alcance a toda la organización. La usas para desplegar flujos y leer analítica.
• dgpk_flow_ — clave publica de flujo, restringida a un flujo concreto.
• dgsk_wh_ — token de webhook, efímero y ligado a un webhook para hacer streaming desde el cliente.

El formato de cada token es el prefijo mas 32 caracteres aleatorios en base62. Daguito guarda solo el hash SHA-256, nunca el valor en claro.

Gestion de claves de cuenta

Las claves de cuenta se crean y revocan desde el panel, no con otra clave de API. Los endpoints siguientes son los mismos que usa el panel: se autentican con tu sesión de administrador (un JWT de propietario de la organización en la cabecera Authorization), no con un token dgsk_acc_. Cada organización puede tener hasta 10 claves activas.

Listar claves

Devuelve las claves de la organización sin el valor en claro:

curl -X GET https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json'

Crear una clave

Crea una clave con un name y, opcionalmente, un monthly_budget_micro_usd (limite de gasto mensual en micro-USD). Responde con 201 e incluye el valor en claro una sola vez.

curl -X POST https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "production", "monthly_budget_micro_usd": 100000000}'

En el ejemplo, 100.000.000 micro-USD equivalen a un presupuesto mensual de 100 USD.

Revocar una clave

Revoca una clave por su id. Responde con 204 sin cuerpo.

curl -X DELETE https://api.daguito.com/v1/account/api-keys/<id> \
  -H 'Authorization: Bearer <session-jwt>'

Forma de la respuesta

Cada clave se representa asi (sin el valor en claro). key_prefix son los primeros 14 caracteres del token, suficientes para identificarlo en una lista sin exponerlo entero:

{
  "id": "uuid",
  "name": "production",
  "key_prefix": "dgsk_acc_AbC1x",
  "monthly_budget_micro_usd": 100000000,
  "current_mtd_micro_usd": 45230000,
  "created_at": "2026-01-15T10:30:00Z",
  "last_used_at": "2026-06-07T14:22:15Z",
  "revoked_at": null
}

API de Flujos

Despliega flujos de forma idempotente desde tu código o tu pipeline de CI. Volver a enviar el mismo slug actualiza el flujo en lugar de duplicarlo.

Crear o actualizar un agente

POST /v1/flows/upsert-agent crea un agente con su trigger a partir de una plantilla (slug, provider, model, system_prompt, herramientas). Requiere una clave dgsk_acc_.

curl -X POST https://api.daguito.com/v1/flows/upsert-agent \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my_agent",
    "name": "My Agent",
    "model": "meta-llama/llama-3.3-70b-instruct",
    "system_prompt": "You are a helpful assistant",
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Subir un flujo personalizado

POST /v1/flows/upsert sube un flujo completo. El cuerpo lleva slug, name y un objeto graph con nodes y edges (y un trigger_type opcional). Acepta una clave dgsk_acc_ o una clave sk_dgt_ con alcance flow:admin.

Resolver el webhook de un flujo

GET /api/sdk/flows?slug=<slug> devuelve el flow_id y el token de webhook que tu cliente usa para hacer streaming. Requiere una clave sk_dgt_ con alcance flow:run.

curl -X GET 'https://api.daguito.com/api/sdk/flows?slug=my_agent' \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json'

API de Conocimiento

Alimenta tus bases de conocimiento e interrogalas con el mismo pipeline de la Base de Conocimiento que usa la plataforma. El org_id siempre se deriva del token, nunca del cuerpo de la petición.

Ingerir texto

POST /api/sdk/knowledge/sources/:id/text ingiere texto con metadata opcional. Requiere una clave sk_dgt_ con alcance kb:write.

curl -X POST https://api.daguito.com/api/sdk/knowledge/sources/<id>/text \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Devoluciones en 30 dias.", "metadata": {"lang": "es"}}'

Buscar en una base

POST /api/sdk/knowledge/search recupera fragmentos relevantes con query, session_id y opcionales source_ids, top_k, enable_rewrite, enable_rerank y enable_cache. Requiere una clave sk_dgt_ con alcance kb:read.

curl -X POST https://api.daguito.com/api/sdk/knowledge/search \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how to reset password",
    "top_k": 5,
    "enable_rerank": true,
    "enable_cache": true
  }'

El alcance por recurso se aplica en cada endpoint: la clave debe tener el permiso de accion correcto y estar autorizada para las bases solicitadas. Si una fuente no existe o pertenece a otra organización, la respuesta es 404 (para no filtrar su existencia); si la clave no tiene alcance, es 403.

Monitoreo y uso

GET /v1/org/analytics devuelve una instantanea de uso del dia de tu organización (contadores del dia en curso mas el conteo de salientes de las ultimas 24 horas). Requiere una clave dgsk_acc_.

curl -X GET https://api.daguito.com/v1/org/analytics \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json'

La respuesta incluye:

• LLM — peticiones, tokens y coste en USD.
• Mensajes — entrantes del dia en curso y salientes de las ultimas 24 horas.
• HTTP — total de llamadas y desglose por ruta.
• Presupuesto — limites y gasto del mes en curso, a nivel de organización y de clave.

Manejo de errores

Los errores siempre llegan como JSON con un único campo de texto:

{
  "error": "API key required"
}

Códigos de estado:

• 400 — validación fallida (por ejemplo, slug mal formado, nombre demasiado largo o JSON invalido).
• 401 — clave ausente, invalida o expirada.
• 403 — clave valida pero sin el alcance requerido (de accion o de recurso).
• 404 — recurso no encontrado o acceso denegado por organización (para no revelar su existencia).
• 500 — error inesperado del servidor.

Limites de tasa

Los limites de tasa aplican solo a los endpoints de widget (chat, formulario, carrito):

• 10 mensajes cada 60 segundos por sesión.
• 100 mensajes cada 3600 segundos por IP.

Se implementan con contadores de ventana deslizante. Cuando se supera el límite, la respuesta indica en milisegundos cuánto esperar:

{
  "allowed": false,
  "retry_after_ms": 4200
}

Los endpoints de SDK y de administracion no tienen limites por petición publicados; el control se hace por presupuesto de gasto.

Credenciales y permisos

Cada credencial tiene un proposito y un alcance distintos:

• Claves de cuenta (dgsk_acc_): alcance a toda la organización, las crea el propietario. Se usan para desplegar flujos (upsert-agent / upsert) y leer la analítica de uso.
• Claves de SDK (sk_dgt_): restringidas a un flujo o a una base, se crean desde el panel. Son las que operan sobre el conocimiento y resuelven webhooks. Declaran su alcance por accion (kb:read, kb:write, flow:run, flow:admin) y por recurso.
• Tokens de webhook (dgsk_wh_): efímeros y ligados a un webhook concreto, para hacer streaming desde el cliente sin incrustar credenciales sensibles.

El alcance se aplica en dos capas: el middleware verifica el alcance por accion, y el handler comprueba el alcance por recurso una vez resuelto el recurso de destino (un valor null equivale a todos los recursos de la organización).

¿Qué sigue?