API · knowledge

GET /knowledge

Listar los ítems de la base de conocimiento del bot

Sesión con cualquier rol, o API key con config:read. Sin paginación (lista completa del workspace).

• Autenticación: Clave de API o sesión del panel
• Scopes: config:read

Parámetros

Respuestas

POST /knowledge

Crear un ítem de conocimiento (texto, FAQ o ítem de catálogo)

Owner/manager con CSRF, o API key con config:write. Con AI_LIMITS_ENABLED activo, admisión externa puede devolver 429 (ai_limit_reached, ai_usage_uncertain, ai_busy, ai_request_rate_limited). Calcula el embedding (503 si no hay proveedor de embeddings configurado, 502 si falla). Auditado.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeItemCreate

Respuestas

PATCH /knowledge/{item_id}

Editar un ítem (nueva versión) o activarlo/desactivarlo

Owner/manager con CSRF, o API key con config:write. Cambiar título o contenido sube version y requiere embedding; con admisión IA activada puede devolver429 ai_limit_reached/ai_usage_uncertain/ai_busy/ai_request_rate_limited sin cambiar el ítem. Cambios de active no usan IA. Auditado.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeItemUpdate

Respuestas

DELETE /knowledge/{item_id}

Dar de baja un ítem (baja lógica)

Owner/manager con CSRF, o API key con config:write. El ítem deja de responder en el bot pero se conserva su historial; devuelve el ítem con active=false.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Parámetros

Respuestas

POST /knowledge/files

Subir un PDF a la base de conocimiento

Owner/manager con CSRF, o API key con config:write. 422 si el PDF es inválido, ilegible o supera el tamaño máximo. El PDF va como cuerpo crudo con Content-Type application/pdf (sin multipart, un archivo por llamada); tamaño máximo acotado por el servidor. Se parte en ítems de tipo file. Admisión IA opt-in puede devolver429 con códigos ai_limit_reached/ai_usage_uncertain/ai_busy/ai_request_rate_limited; una denegación revierte la ingesta.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:write

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/pdf: string

Respuestas

GET /knowledge/live-queries

GET consulta HTTP en vivo (F2-49)

Solo sesión owner/manager; escrituras con CSRF. API keys sin acceso. HTTPS GET público con IP fijada y validación por salto, 3 s totales, 64 KiB descomprimidos y 2 KiB mapeados. Credenciales cifradas de escritura únicamente. Schema cerrado de hasta 8 parámetros escalares, mapeo declarativo. Máximo 10 consultas; expected_version evita sobrescribir cambios. La baja desactiva y conserva historial. Pruebas aplican cache tenant/consulta/versión/parámetros, cuotas y circuito como el bot; errores externos son resultado ok=false sin contenido crudo. Sin PII en auditoría.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Respuestas

POST /knowledge/live-queries

POST consulta HTTP en vivo (F2-49)

Solo sesión owner/manager; escrituras con CSRF. API keys sin acceso. HTTPS GET público con IP fijada y validación por salto, 3 s totales, 64 KiB descomprimidos y 2 KiB mapeados. Credenciales cifradas de escritura únicamente. Schema cerrado de hasta 8 parámetros escalares, mapeo declarativo. Máximo 10 consultas; expected_version evita sobrescribir cambios. La baja desactiva y conserva historial. Pruebas aplican cache tenant/consulta/versión/parámetros, cuotas y circuito como el bot; errores externos son resultado ok=false sin contenido crudo. Sin PII en auditoría.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Cuerpo de la solicitud (obligatorio)

• application/json: LiveQueryCreate

Respuestas

PUT /knowledge/live-queries/{query_id}

PUT consulta HTTP en vivo (F2-49)

Solo sesión owner/manager; escrituras con CSRF. API keys sin acceso. HTTPS GET público con IP fijada y validación por salto, 3 s totales, 64 KiB descomprimidos y 2 KiB mapeados. Credenciales cifradas de escritura únicamente. Schema cerrado de hasta 8 parámetros escalares, mapeo declarativo. Máximo 10 consultas; expected_version evita sobrescribir cambios. La baja desactiva y conserva historial. Pruebas aplican cache tenant/consulta/versión/parámetros, cuotas y circuito como el bot; errores externos son resultado ok=false sin contenido crudo. Sin PII en auditoría.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: LiveQueryUpdate

Respuestas

DELETE /knowledge/live-queries/{query_id}

DELETE consulta HTTP en vivo (F2-49)

Solo sesión owner/manager; escrituras con CSRF. API keys sin acceso. HTTPS GET público con IP fijada y validación por salto, 3 s totales, 64 KiB descomprimidos y 2 KiB mapeados. Credenciales cifradas de escritura únicamente. Schema cerrado de hasta 8 parámetros escalares, mapeo declarativo. Máximo 10 consultas; expected_version evita sobrescribir cambios. La baja desactiva y conserva historial. Pruebas aplican cache tenant/consulta/versión/parámetros, cuotas y circuito como el bot; errores externos son resultado ok=false sin contenido crudo. Sin PII en auditoría.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Respuestas

POST /knowledge/live-queries/{query_id}/test

POST consulta HTTP en vivo (F2-49)

Solo sesión owner/manager; escrituras con CSRF. API keys sin acceso. HTTPS GET público con IP fijada y validación por salto, 3 s totales, 64 KiB descomprimidos y 2 KiB mapeados. Credenciales cifradas de escritura únicamente. Schema cerrado de hasta 8 parámetros escalares, mapeo declarativo. Máximo 10 consultas; expected_version evita sobrescribir cambios. La baja desactiva y conserva historial. Pruebas aplican cache tenant/consulta/versión/parámetros, cuotas y circuito como el bot; errores externos son resultado ok=false sin contenido crudo. Sin PII en auditoría.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: LiveQueryTest

Respuestas

POST /knowledge/search

Buscar en la base de conocimiento (lo mismo que ve el bot)

Sesión con cualquier rol, o API key con config:read. Búsqueda semántica; sirve al simulador del panel. Con admisión IA activada puede devolver429 ai_limit_reached/ai_usage_uncertain/ai_busy/ai_request_rate_limited.

• Autenticación: Clave de API o sesión del panel
• Scopes: config:read

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeSearch

Respuestas

GET /knowledge/sources

Listar las fuentes web de la base de conocimiento

Solo sesión (cualquier rol); las API keys no tienen acceso a las fuentes (traen URLs, se mantienen en el panel). Sin paginación (máximo 10 por workspace).

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Respuestas

POST /knowledge/sources

Registrar una página web o un listado como fuente de conocimiento (F2-47, F2-48)

Solo sesión owner/manager con CSRF. La URL debe ser http(s) pública: se valida contra SSRF (IPs privadas, loopback, link-local/metadata, credenciales en la URL, DNS) y vuelve a validarse en cada traída y en cada redirección; 422 unsafe_source_url si no es válida. La URL tampoco puede llevar secretos en el query (?api_key=…, ?token=… y variantes: 422 unsafe_source_url; las credenciales van por fuera de la URL). No hace la traída: queda pending y el worker la importa en su próximo ciclo (≤ 1 min), una sola página, sin JavaScript, respetando robots.txt, solo text/html/text/plain, tope de tamaño. Los ítems importados son de tipo web y el bot los recibe como dato citado no confiable, nunca como instrucción. Tope de 10 fuentes por workspace (409 knowledge_source_limit_reached); URL repetida 409 knowledge_source_duplicate. Auditado. F2-48: kind = csv, json, rss o sheet registra un listado estructurado (misma traída segura, sin robots.txt, tope 2 MiB y 1000 filas) con mapping declarativo y credentials opcionales (cifradas, nunca devueltas); los ítems son de tipo listing. 422 knowledge_invalid_mapping si el mapeo no es válido. kind=site importa una SECCIÓN: url es el prefijo (p. ej. https://fiuit.com/es/docs); el worker lee el sitemap.xml del dominio (y sus índices), toma solo las URLs del mismo host que cuelgan del prefijo (hasta max_pages, 50 por defecto, máx. 200) y trae cada una con la misma traída segura (SSRF, tamaño, tiempo, robots.txt, sin seguir a otros dominios). Cada refresco agrega las páginas nuevas, actualiza las que cambiaron (hash del contenido) y archiva las que desaparecieron. Sin sitemap: last_error=no_sitemap.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeSourceCreate

Respuestas

GET /knowledge/sources/{source_id}

Ver una fuente web (estado, último refresco, error legible)

Solo sesión (cualquier rol). last_error es un código corto (blocked_address, robots_disallowed, too_large, unsupported_content_type, timeout, empty_content...), nunca el texto de una excepción.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Respuestas

PATCH /knowledge/sources/{source_id}

Cambiar el intervalo de refresco o pausar/reanudar una fuente

Solo sesión owner/manager con CSRF. paused=true detiene el refresco (los ítems ya importados siguen disponibles); paused=false la reanuda y la agenda de inmediato. Auditado.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeSourceUpdate

Respuestas

DELETE /knowledge/sources/{source_id}

Borrar una fuente y los ítems que importó

Solo sesión owner/manager con CSRF. Los ítems manuales no se tocan. Auditado.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Respuestas

GET /knowledge/sources/{source_id}/pages

Páginas importadas de una fuente de sección (kind=site)

Solo sesión (cualquier rol). Una fila por página con su estado (ok o archived). Vacío para los demás tipos de fuente.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Respuestas

POST /knowledge/sources/{source_id}/refresh

Pedir un refresco inmediato de una fuente

Solo sesión owner/manager con CSRF. Agenda la fuente para el próximo ciclo del worker y reanuda una pausada (reinicia el contador de errores; si la fuente está en error, el contador se conserva para que los reprogramados cortos no reintenten en bucle); la traída no ocurre dentro de la petición. Devuelve 409 knowledge_source_refresh_cooldown si la última traída exitosa fue hace menos de KNOWLEDGE_REFRESH_COOLDOWN_MINUTES (15 por defecto). Sin cambios en el contenido (mismo content_hash) no se vuelven a generar embeddings. Auditado.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Parámetros

Respuestas

POST /knowledge/sources/preview

Vista previa de un listado, sin guardar (F2-48)

Solo sesión owner/manager con CSRF. Trae el listado con la misma traída segura que el worker y devuelve las primeras filas ya mapeadas (máx. 10), el total leído y las columnas/claves detectadas, para validar el mapeo ANTES de crear la fuente. No guarda nada (ni la fuente ni la credencial) y no devuelve la credencial. Límite: 10 vistas previas por minuto y workspace (429 knowledge_preview_rate_limited). 422 knowledge_listing_failed con reason (código corto: blocked_address, invalid_url, too_large, unsupported_content_type, http_error, timeout, invalid_listing, empty_content, mapping_column_missing, invalid_mapping...) o knowledge_invalid_mapping.

• Autenticación: Clave de API o sesión del panel
• Scopes: Ninguno

Cuerpo de la solicitud (obligatorio)

• application/json: KnowledgeSourcePreview

Respuestas