Semantia API

Semantia API te permite usar el conocimiento indexado de tu cuenta desde fuera de la aplicación: en tu propio backend, en un chatbot (n8n, LangChain, etc.) o con un widget embebible en tu sitio web.

Dónde configurarlo

En la app, entra a Semantia API en el menú lateral (visible para administradores y dueños de la cuenta).

Desde ahí puedes:

• Crear y revocar claves API
• Configurar el widget (apariencia, mensajes, dominios)
• Registrar webhooks para recibir eventos en tu servidor
• Ver el uso mensual (chat, búsquedas y tráfico solo vía API)

Claves API

Hay dos tipos de clave:

Tipo	Prefijo	Dónde usarla
Secreta	sk_live_…	Tu servidor, scripts, automatizaciones
Pública	pk_widget_…	Solo en el navegador (widget embebido)

La clave completa se muestra una sola vez al crearla. Guárdala en un gestor de secretos; no la compartas en repositorios públicos ni en el front-end (salvo la clave pública del widget).

Clave secreta

Incluye permisos de chat (respuestas RAG con fuentes) y búsqueda (consultas semánticas sin generar texto). Envíala en cada request:

Authorization: Bearer sk_live_…

También puedes usar el header X-Semantia-Key.

Clave pública (widget)

Solo funciona desde los dominios que configures al crearla (por ejemplo https://www.tu-empresa.com). Semantia valida el header Origin del navegador.

Cada plan tiene un límite de dominios únicos para widgets; el panel muestra cuántos llevas usados.

Endpoints públicos

Base de producción: https://api.semantia.com.co

Método	Ruta	Descripción
POST	/v1/public/chat	Pregunta y respuesta JSON con fuentes
POST	/v1/public/chat/stream	Igual, con streaming SSE
POST	/v1/public/search	Búsqueda semántica por documento (sin LLM)
POST	/v1/public/retrieve	Fragmentos (chunks) para RAG propio
GET	/v1/public/widget/config	Configuración del widget (clave pública)
POST	/v1/public/widget/chat/stream	Chat del widget (clave pública, SSE)

Ejemplo: chat

curl -X POST https://api.semantia.com.co/v1/public/chat \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"message":"¿Cuáles contratos vencen este mes?"}'

Campos útiles en el body:

• message — obligatorio
• session_id — para continuar una conversación (TTL 24 h en servidor)
• document_id — limitar la respuesta a un documento
• category_code — filtrar por categoría
• mode — chat (por defecto) o synthesis (informe estructurado)

La respuesta incluye sources[] con los documentos usados, igual que en el asistente de la app.

Ejemplo: búsqueda

curl -X POST https://api.semantia.com.co/v1/public/search \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"condiciones de pago","limit":10}'

Ejemplo: retrieve (chunks)

Para integraciones RAG avanzadas que arman el contexto en tu propio LLM:

curl -X POST https://api.semantia.com.co/v1/public/retrieve \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"plazos de entrega","limit":20}'

Devuelve una lista de chunks con texto, puntuación y metadatos del documento.

Cuotas y planes

• Los mensajes de chat de la app, la API y el widget comparten el límite mensual de tu plan.
• Las búsquedas y el retrieve consumen el cupo de búsquedas del mes.
• El contador Solo vía API en el panel es analítico (cuántos mensajes llegaron por API/widget, sin bloqueo aparte).

El plan Gratis no incluye Semantia API. Los planes de pago la habilitan según los límites de Facturación.

Widget embebible

Pega este snippet antes de </body> en tu sitio (sustituye la clave por tu pk_widget_…):

<script
  src="https://api.semantia.com.co/widget/v1/semantia-widget.js"
  data-key="pk_widget_…"
  async
></script>

Opcionalmente puedes sobrescribir título, color o posición con atributos data-title, data-color, data-position.

En Semantia API → Widget ajustas:

• Mensaje de bienvenida y placeholder
• Colores y posición (esquina inferior izquierda o derecha)
• Si se muestran las fuentes en cada respuesta
• Si el widget está activo o pausado

El widget recuerda la conversación mientras la pestaña del navegador siga abierta (usa sessionStorage, que se borra al cerrarla). En el servidor, esa sesión permanece disponible hasta 24 horas después del último mensaje — si el visitante vuelve a abrir la página dentro de ese tiempo con la misma pestaña, retoma la conversación donde la dejó.

Webhooks

Puedes registrar URLs en tu servidor para recibir notificaciones cuando ocurren eventos en tu cuenta.

Eventos disponibles:

Evento	Cuándo se envía
chat.completed	Tras una respuesta de chat vía API o widget
quota.warning	Al superar el 80 % del cupo mensual de chat o búsquedas
api_key.created	Al crear una clave
api_key.revoked	Al revocar una clave

Cada entrega es un POST JSON con cabeceras:

• X-Semantia-Event — tipo de evento
• X-Semantia-Signature — firma HMAC-SHA256 (t={timestamp},v1={hash})

Verifica la firma con el secreto whsec_… que recibes al crear el webhook (solo se muestra una vez). El cuerpo tiene forma:

{
  "id": "evt_…",
  "type": "chat.completed",
  "created_at": "2026-07-07T12:00:00+00:00",
  "account_id": 123,
  "data": { }
}

El número de webhooks activos depende de tu plan.

Errores frecuentes

Código	Significado habitual
401	Clave ausente, incorrecta o revocada
403	Plan sin API, dominio no autorizado (widget) o cuenta suspendida
429	Cuota mensual agotada o demasiadas solicitudes por minuto
404	Sesión de chat expirada o no encontrada

Los errores de la API pública devuelven JSON con error y message legibles.

Buenas prácticas

• Usa claves secretas solo en el servidor; nunca las expongas en JavaScript del cliente.
• Configura todos los dominios desde los que cargarás el widget (incluye www y sin www si aplica).
• Revoca de inmediato cualquier clave que pueda haberse filtrado.
• Informa a los visitantes de tu web que interactúan con un asistente basado en tus documentos.

Más detalle técnico

• Los orígenes permitidos de una clave pública se validan por el header Origin (o Referer si el navegador no envía Origin) — funciona como protección contra reuso accidental desde otro sitio, pero no es una barrera contra alguien que copie la clave y la use fuera del navegador (por ejemplo, desde un script). No la trates como si fuera secreta.
• Límites de tasa: 120 solicitudes/minuto para claves secretas, 30/minuto para claves públicas (por IP), con un techo adicional por clave sumando todas las IPs.
• Si necesitas la especificación técnica completa (arquitectura interna, esquemas de request/response), contacta al equipo de producto.