Alimentar la base de conocimiento

POST /kb-files sube un documento a la biblioteca del workspace y POST /kb/sources guarda una entrada redactada a mano. Las dos terminan en el mismo texto indexado que el agente busca y cita. Elegir una u otra es una decisión de flujo de trabajo.

• Archivos (/kb-files): un documento subido, o generado desde una web.
• Fuentes manuales (/kb/sources): un problema, su causa y los pasos de solución.

Leer pide kb:read; escribir, kb:write.

Subir un archivo

curl -X POST https://api.vitrinadev.com/api/v1/kb-files \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -F "[email protected]"

{
  "data": {
    "id": "a6a6a6a6-0000-4000-8000-000000000001",
    "name": "Garantías 2026.pdf",
    "content_type": "application/pdf",
    "size_bytes": 182304,
    "status": "ready",
    "agents": []
  }
}

El archivo queda en la biblioteca del workspace, sin adjuntarse a ningún agente. Adjuntarlo es un paso aparte, con POST /ai-agents/{id}/knowledge.

status es el estado de la ingesta y no el de la subida. ready significa que los bytes llegaron, todavía no que se pueda buscar en el archivo. La ingesta corre aparte. Si un archivo sigue en ready y no aparece en las búsquedas, POST /kb-files/{id}/reingest la reintenta.

Tope: 25 MB por archivo.

Generar desde una web

Para no volver a escribir lo que ya está publicado en el sitio del workspace:

curl -X POST https://api.vitrinadev.com/api/v1/kb-files/generate-from-url \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.miempresa.cl/garantia" }'

{
  "data": {
    "title": "Garantía — Mi Empresa",
    "markdown": "# Garantía\n\nTodos los vehículos nuevos incluyen 3 años o 100.000 km de garantía de fábrica.",
    "source_url": "https://www.miempresa.cl/garantia",
    "page_count": 1
  }
}

El resultado se devuelve y no se guarda. Nada queda buscable todavía. Es el borrador que alguien tiene que revisar antes de que el agente se lo cite a un cliente. Guardarlo es un POST /kb-files normal, con el markdown como contenido.

Con crawl: true y max_pages rastrea varias páginas de una vez, pero la llamada se demora lo que se demoren el rastreo y el LLM. Para un sitio grande, usa el flujo asíncrono:

curl -X POST https://api.vitrinadev.com/api/v1/kb-files/crawl/start \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.miempresa.cl", "max_pages": 10 }'

Devuelve un job_id de inmediato. Guárdalo: es la única credencial sobre ese rastreo. GET /kb-files/crawl/{jobId} informa el progreso. Ahí lee done en vez de status: done es verdadero para todo estado terminal, incluidos los que fallaron. POST /kb-files/crawl/{jobId}/generate consolida lo rastreado en un documento, igual que la versión síncrona.

Reemplazar en vez de borrar y volver a subir

Cuando cambia el contenido de un documento ya adjunto a agentes, reemplazarlo conserva el id. Con él conserva cada adjunto y cada versión de agente que lo referencia:

curl -X PUT https://api.vitrinadev.com/api/v1/kb-files/a6a6a6a6-0000-4000-8000-000000000001/content \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -F "[email protected]"

Los chunks anteriores se purgan en la misma transacción que el reemplazo, así que el agente nunca cita el texto viejo mientras corre la nueva ingesta.

Borrar

curl -X DELETE https://api.vitrinadev.com/api/v1/kb-files/a6a6a6a6-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer $VITRINA_KEY"

El borrado es suave. El archivo sale de la biblioteca, se desadjunta de todo agente y sus chunks se purgan. Restaurar una versión de agente que lo usaba lo recupera.

Para sacar un archivo de un solo agente sin tocar a los demás, usa DELETE /ai-agents/{id}/knowledge/{fileId}.

Fuentes manuales

Para una respuesta que no vive en ningún documento, algo que el equipo sabe y quiere que el agente sepa también:

curl -X POST https://api.vitrinadev.com/api/v1/kb/sources \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": {
      "title": "Horario de atención",
      "problem": "El cliente pregunta el horario de atención",
      "solution_steps": [
        "Confirmar el horario: lunes a viernes de 9:00 a 19:00",
        "Ofrecer agendar una cita si corresponde"
      ]
    },
    "tags": ["horarios", "atencion"]
  }'

Nace en status: "pending" y sin chunks, así que crearla no la hace buscable. PUT /kb/sources/{id} es el paso de revisión, por ejemplo para pasarla a status: "approved". Ninguna de las dos llamadas la embebe por su cuenta:

curl -X POST https://api.vitrinadev.com/api/v1/kb/sources/a5a5a5a5-0000-4000-8000-000000000001/embed \
  -H "Authorization: Bearer $VITRINA_KEY"

Esa es la llamada que la vuelve buscable. Repetirla es seguro: borra los chunks anteriores de la fuente antes de insertar los nuevos, así una fuente nunca se duplica en la búsqueda.

POST /kb/sources/{id}/revoke es la alternativa reversible a borrar. La fila y sus chunks sobreviven, pero la fuente sale de la lista por defecto (?status=active). Vuelve cuando se la aprueba y se la embebe otra vez. DELETE /kb/sources/{id} sí es definitivo: la fila y sus chunks se van sin vuelta atrás.

Los eventos

No hay evento de actualización para un archivo. Reemplazar sus bytes conserva el id y no cambia ningún estado sobre el que un receptor deba actuar distinto.