Base de Conocimientos

Cada agente tiene una colección de entradas de conocimiento — fragmentos de información que el agente puede consultar en tiempo de ejecución para responder con datos específicos de tu negocio (manuales, políticas, FAQs, fichas de producto, etc.).

Cuando subes un archivo o ingieres una URL, Platica se encarga del procesamiento automático: extrae el contenido, genera un título y descripción si no los proveíste, lo divide en fragmentos si es muy largo, deduplica si el archivo ya existía, e indexa todo para que el agente pueda buscarlo.

Listar Entradas

GET https://api.platica.mx/v1/agents/{agentId}/knowledge

Parámetros de URL

Parámetros de query

Respuesta

{
  "count": 1,
  "knowledge": [
    {
      "id": "FXjQXMr3...",
      "name": "get_politicas_devolucion_a1b2c3",
      "topic": "Políticas de devolución",
      "description": "Documento oficial v2.3 con plazos, condiciones y excepciones.",
      "status": "active",
      "fileType": "pdf",
      "fileName": "manual.pdf",
      "lastUpdate": "2026-05-28T06:14:21.000Z"
    }
  ]
}

Obtener Entrada

GET https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

Parámetros de URL

Respuesta

Devuelve la entrada completa, incluyendo el contenido ya procesado.

Crear desde URLs

Cuando el archivo ya está alojado públicamente (Firebase Storage, S3, etc.), referencialo por URL y Platica lo descarga y procesa.

POST https://api.platica.mx/v1/agents/{agentId}/knowledge

Parámetros de URL

Cuerpo de la solicitud

{
  "files": [
    {
      "fileUrl": "https://storage.googleapis.com/.../manual.pdf",
      "fileName": "manual.pdf",
      "fileType": "pdf",
      "topic": "Manual del producto",
      "description": "Manual oficial v2.3"
    }
  ],
  "setActive": true
}

Respuesta

{
  "status": "success",
  "message": "Knowledge entries created",
  "data": {
    "totalFiles": 1,
    "successful": 1,
    "failed": { "count": 0, "files": [] }
  }
}

Crear desde texto

Si no tienes un archivo, crea la entrada directamente desde texto crudo enviando content en lugar de fileUrl. Es el mismo endpoint POST .../knowledge; solo cambia el contenido de files[]:

{
  "files": [
    {
      "fileName": "politica-devoluciones.txt",
      "fileType": "txt",
      "content": "Aceptamos devoluciones dentro de los 30 días posteriores a la compra...",
      "topic": "Devoluciones",
      "description": "Política de devoluciones"
    }
  ],
  "setActive": true
}

Con content, Platica omite la descarga y el parseo: usa el texto tal cual. Si envías topic y description, se salta la generación automática con IA; si los omites, se generan a partir del texto. La respuesta es idéntica a crear desde URLs .

Subir Archivos

Para subir el binario directamente sin pre-hostear, manda multipart al endpoint de upload. Platica lo guarda, lo hace accesible vía URL pública y te devuelve esa URL para que la pases a crear desde URLs .

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/upload

Parámetros de URL

Cuerpo de la solicitud

Content-Type: multipart/form-data con uno o más campos files:

curl -X POST https://api.platica.mx/v1/agents/{agentId}/knowledge/upload \
  -H "Authorization: Bearer pl_key_..." \
  -F "files=@manual.pdf" \
  -F "files=@politicas.docx"

Límite: 20 MB por request multipart.

Respuesta

{
  "status": "success",
  "message": "Files uploaded",
  "data": {
    "success": true,
    "uploaded": [
      {
        "fileName": "manual.pdf",
        "fileUrl": "https://storage.googleapis.com/.../manual.pdf",
        "fileType": "pdf",
        "fileSize": 481923
      }
    ]
  }
}

Ingerir URLs Web

Ingesta el contenido de páginas web, lo convierte a texto y crea entradas de conocimiento con título y descripción generados automáticamente.

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/web

Parámetros de URL

Cuerpo de la solicitud

{
  "urls": [
    "https://docs.miempresa.com/faq",
    "https://miempresa.com/politicas/devoluciones"
  ]
}

Respuesta

{
  "status": "success",
  "message": "Web pages ingested",
  "data": {
    "totalUrls": 2,
    "successful": 2,
    "failed": { "count": 0, "details": [] }
  }
}

Actualizar Entrada

Actualiza una entrada existente: agrega texto al contenido, lo reemplaza por completo, cambia metadata o estado, o re-procesa la fuente original.

PATCH https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

Parámetros de URL

Cuerpo de la solicitud

Cambiar status:

{ "status": "active" }

Agregar texto al final del contenido (sin reescribir lo existente):

{ "appendContent": "Nuevo párrafo que se agrega al final." }

Reemplazar el contenido directamente (sobrescribe todo el texto). También puedes actualizar topic y description:

{ "content": "Nuevo contenido completo de la entrada...", "topic": "Devoluciones", "description": "Política actualizada" }

Re-procesar la fuente original (re-extrae y re-genera metadata):

{ "reprocess": true }

Respuesta

{
  "status": "success",
  "message": "Knowledge entry updated"
}

Eliminar Entrada

Elimina una entrada de la base de conocimientos del agente. El agente deja de poder consultarla.

DELETE https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

Parámetros de URL

Respuesta

{
  "status": "success",
  "message": "Knowledge entry deleted"
}

Re-procesar Entrada

Vuelve a procesar la fuente original de una entrada (descarga el archivo o URL otra vez, re-extrae el contenido y regenera la metadata).

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}/reparse

Parámetros de URL

Cuerpo de la solicitud

{ "web": false }

También se acepta { "source": "web" } como alias.

Respuesta

{
  "status": "success",
  "message": "Knowledge entry reparse queued"
}

Notas

• Si subes un archivo idéntico al de una entrada existente (mismo contenido), el sistema deduplica y no crea una nueva.
• Para archivos muy largos, el contenido se divide en varias entradas relacionadas para mantener una buena calidad de búsqueda.