Base de Conocimiento

La base de conocimiento permite ampliar un agente con material de referencia - preguntas frecuentes, detalles de producto, precios, politicas o cualquier contenido especifico del dominio - sin tener que incluirlo todo en el prompt del sistema. Cada entrada se divide en fragmentos y se convierte en embeddings para que el agente pueda recuperar los pasajes mas relevantes durante una conversacion.

Las entradas pertenecen a un unico agente y viven bajo /agents/{agent_id}/knowledge. Todos los endpoints aceptan la misma autenticacion que el resto de la API publica: envia tu clave en la cabecera X-API-Key (tambien funciona un JWT Bearer). La URL base es https://api.usevocals.com/api/v1.

Ciclo de Vida de la Ingesta

Crear una entrada es asincrono. Los endpoints de creacion devuelven 201 Created de inmediato con status en pending; luego el contenido se fragmenta y se convierte en embeddings en segundo plano. Consulta la entrada hasta que se estabilice:

1. Crea una entrada text, url o file -> 201 con status: "pending".
2. La ingesta se ejecuta en segundo plano (fragmentacion + embeddings). El estado pasa de processing a ready.
3. Consulta GET /agents/{agent_id}/knowledge/{entry_id} hasta que status sea ready (utilizable) o error.
4. Si status es error, el motivo esta en error_message.

Si una entrada queda en error con un mensaje de embeddings o de autenticacion, el tenant del agente necesita un proveedor de embeddings funcional configurado - un proveedor OpenAI o los embeddings gestionados de la plataforma. Una vez configurado, llama al endpoint de reprocesamiento para reintentar la entrada.

Esquema de la Entrada

KnowledgeEntryResponse lo devuelven los endpoints de listado, obtencion y creacion.

Campo	Tipo	Descripcion
id	uuid	ID de la entrada
agent_id	uuid	ID del agente propietario
source_type	string	text, url o file
title	string	Titulo de la entrada
source_url	string | null	URL de origen (solo entradas URL)
file_size_bytes	integer | null	Tamano del archivo subido (solo entradas de archivo)
mime_type	string | null	Tipo MIME detectado (solo entradas de archivo)
status	string	pending, processing, ready o error
error_message	string | null	Motivo del fallo cuando status es error (p. ej. un error de embeddings)
chunk_count	integer	Numero de fragmentos con embeddings generados
created_at	datetime	Marca de tiempo de creacion
updated_at	datetime	Marca de tiempo de la ultima actualizacion

Endpoints

Metodo	Ruta	Proposito
GET	/agents/{agent_id}/knowledge/	Lista todas las entradas del agente (mas recientes primero)
POST	/agents/{agent_id}/knowledge/text	Crea una entrada a partir de texto
POST	/agents/{agent_id}/knowledge/url	Crea una entrada a partir de una URL web
POST	/agents/{agent_id}/knowledge/file	Crea una entrada a partir de un archivo subido
GET	/agents/{agent_id}/knowledge/{entry_id}	Obtiene una entrada
DELETE	/agents/{agent_id}/knowledge/{entry_id}	Elimina una entrada (y sus fragmentos + archivo almacenado)
POST	/agents/{agent_id}/knowledge/{entry_id}/reprocess	Reejecuta la ingesta de una entrada

La raiz de la coleccion (/agents/{agent_id}/knowledge/) solo admite GET. Para crear una entrada, envia un POST a una de las sub-rutas text, url o file - hacer POST a la raiz devuelve 405 Method Not Allowed.

Cada agente puede tener hasta 50 entradas por defecto; crear otra por encima del limite devuelve 400 Bad Request.

Listar Entradas

GET /agents/{agent_id}/knowledge/

Devuelve todas las entradas del agente, mas recientes primero.

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "9f8b7c6d-1234-4a5b-9c8d-abcdef012345",
    "source_type": "text",
    "title": "Refund Policy",
    "source_url": null,
    "file_size_bytes": null,
    "mime_type": null,
    "status": "ready",
    "error_message": null,
    "chunk_count": 3,
    "created_at": "2026-06-01T10:30:00Z",
    "updated_at": "2026-06-01T10:30:12Z"
  }
]

Crear Entrada de Texto

POST /agents/{agent_id}/knowledge/text

Cuerpo de la Peticion

{
  "title": "Refund Policy",
  "content": "Refunds are available within 30 days of purchase..."
}

Campo	Tipo	Requerido	Descripcion
title	string	Si	Titulo de la entrada
content	string	Si	Texto a ingerir

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/text \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund Policy",
    "content": "Refunds are available within 30 days of purchase..."
  }'

Respuesta

201 Created - Devuelve el KnowledgeEntryResponse con status: "pending". La ingesta se ejecuta en segundo plano.

Crear Entrada desde URL

POST /agents/{agent_id}/knowledge/url

Descarga la pagina de la URL indicada e ingiere su contenido en segundo plano.

Cuerpo de la Peticion

{
  "url": "https://example.com/docs/pricing",
  "title": "Pricing Page"
}

Campo	Tipo	Requerido	Descripcion
url	string	Si	URL a descargar e ingerir
title	string | null	No	Titulo opcional; se deriva de la pagina si se omite

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/url \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/docs/pricing",
    "title": "Pricing Page"
  }'

Respuesta

201 Created - Devuelve el KnowledgeEntryResponse con status: "pending".

Crear Entrada desde Archivo

POST /agents/{agent_id}/knowledge/file

Sube un documento como multipart/form-data. El texto se extrae en el servidor y luego se ingiere en segundo plano.

Campos del Formulario

Campo	Tipo	Requerido	Descripcion
file	file	Si	El documento a subir
title	string	No	Titulo opcional; se deriva del nombre del archivo si se omite

Tipos de archivo permitidos:

Tipo	Tipo MIME
PDF	application/pdf
Word (.docx)	application/vnd.openxmlformats-officedocument.wordprocessingml.document
Texto plano	text/plain
HTML	text/html
Markdown	text/markdown

El tamano maximo de subida es 10 MB por defecto. Los archivos por encima del limite, o con un tipo MIME no admitido, se rechazan con 400 Bad Request.

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/file \
  -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  -F "file=@handbook.pdf" \
  -F "title=Employee Handbook"

Respuesta

201 Created - Devuelve el KnowledgeEntryResponse con status: "pending".

Obtener Entrada

GET /agents/{agent_id}/knowledge/{entry_id}

Obtiene una entrada. Usalo para consultar el estado de la ingesta tras la creacion.

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id}

Respuesta

200 OK - Devuelve el KnowledgeEntryResponse. Una entrada finalizada muestra status: "ready"; una fallida muestra status: "error" con el motivo en error_message.

Eliminar Entrada

DELETE /agents/{agent_id}/knowledge/{entry_id}

Elimina permanentemente una entrada junto con sus fragmentos con embeddings y cualquier archivo almacenado.

curl -X DELETE https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id} \
  -H "X-API-Key: voc_a1b2c3d4e5f6..."

Respuesta

204 No Content - Sin cuerpo de respuesta.

Reprocesar Entrada

POST /agents/{agent_id}/knowledge/{entry_id}/reprocess

Reejecuta la ingesta de una entrada existente, restableciendo su status a pending. Usalo para reintentar una entrada que quedo en error tras un fallo de ingesta transitorio o despues de corregir el proveedor de embeddings del tenant.

curl -X POST https://api.usevocals.com/api/v1/agents/{agent_id}/knowledge/{entry_id}/reprocess \
  -H "X-API-Key: voc_a1b2c3d4e5f6..."

Respuesta

200 OK - Devuelve el KnowledgeEntryResponse con status: "pending". Consulta el endpoint de obtencion hasta que se estabilice.