Introducción a la API

La API de Kelova te permite indexar documentos de tu empresa, consultar a tus agentes RAG y conectar el conocimiento indexado a cualquier agente IA externo vía MCP. Esta referencia cubre los endpoints pensados para integraciones de cliente — autenticación, gestión de fuentes, agentes, límites de uso y el servidor MCP por tenant.

Base URL

https://api.kelova.app

Todos los ejemplos de esta referencia usan esta base URL. No existe un ambiente "sandbox" público — para pruebas usa un tenant real en plan Free.

Autenticación

La mayoría de los endpoints requieren un JWT en el header Authorization:

Authorization: Bearer <token>

El token se obtiene con POST /auth/login y expira a las 8 horas. Ver Autenticación para el flujo completo, incluido el segundo factor (OTP).

El servidor MCP (POST /mcp/{tenant_slug}) usa un mecanismo distinto: una API key de larga duración en el mismo header Authorization: Bearer <api_key>. Ver MCP.

Formato de las respuestas

Todas las respuestas son JSON. Las respuestas exitosas devuelven directamente el recurso (objeto o array) — no hay un envoltorio data.

{
  "source_id": "3f2e1a...",
  "name": "Catálogo 2026",
  "sync_status": "pending"
}

Los errores usan un envoltorio estándar {"error": {...}}. Ver Errores para el detalle completo, incluidos los códigos estables por dominio.

Multi-tenant y trazabilidad

Cada request autenticado con JWT opera sobre un único tenant — el tenant_id viaja embebido en el token y el backend lo usa para filtrar todos los datos (Row-Level Security). No existe un parámetro tenant_id en el body ni en query string: nunca lo envíes, se ignora.

Cada respuesta de un agente que cita documentos incluye la fecha de sincronización (synced_at) de cada fuente usada — así tu integración puede mostrar qué tan fresca es la información.

Convenciones

• Todas las fechas son ISO 8601 / RFC 3339 en UTC ("2026-07-10T14:32:00Z").
• Los IDs de recursos (source_id, agent_id, endpoint_id) son UUID v4 en formato string.
• Los endpoints de escritura (POST, PUT, PATCH, DELETE) requieren rol admin en el tenant, salvo que se indique lo contrario en cada página. Los de lectura aceptan admin o member.
• Un tenant en estado suspended conserva acceso de lectura y puede seguir consultando a sus agentes, pero no puede indexar fuentes nuevas ni crear agentes o endpoints MCP nuevos.

Siguientes pasos