API de la base de conocimientos

Tu base de conocimientos es de donde lee la IA. Consta de dos partes, y esta página cubre ambas:

Fuentes de conocimiento (/kb-sources): las páginas web y los documentos cargados que proporcionas a la plataforma. Cada uno se lee, se divide en secciones y se convierte en preguntas frecuentes (FAQs) que tu IA puede responder.
Grupos de conocimiento (/kb-groups): conjuntos de preguntas frecuentes con nombre que puedes aplicar a un agente o a una campaña en una sola llamada, de modo que un cuerpo de conocimientos que ya hayas seleccionado pueda reutilizarse en el siguiente agente que crees.

Las preguntas frecuentes que produce una fuente terminan en la misma biblioteca que las que escribes a mano, por lo que una vez que finaliza una importación, puedes leerlas, editarlas y vincularlas con la API de preguntas frecuentes.

Todos los endpoints a continuación son relativos a la URL base https://api.youraiconnector.com/v1. Cada solicitud debe estar autenticada; consulta Acceso a la API y Autenticación. El acceso a la API es una función de pago; sin ella, las solicitudes se rechazan con un 403.

La importación consume créditos. Leer una página o documento y redactar preguntas frecuentes a partir de él consume créditos, aproximadamente en proporción a la cantidad de contenido que haya. Utiliza Estimar una importación antes de realizar un rastreo grande.

Cómo funciona una importación

La importación es una tarea en segundo plano, no algo que finaliza mientras esperas. Cada endpoint de importación responde inmediatamente con un source_id, y debes consultar esa fuente hasta que termine:

Iniciar la importación — POST /kb-sources/url (una página), POST /kb-sources/file (un documento cargado) o POST /kb-sources/bulk-import (hasta 100 páginas). Obtendrás un ID de fuente y un status: "queued".
Consultar — GET /kb-sources/{sourceId} hasta que status ya no sea queued o processing.
Leer las preguntas frecuentes — cuando el estado es ready, las entradas que produjo están en tu biblioteca de preguntas frecuentes: GET /faqs.

Cada fuente informa uno de estos estados:

Estado	Qué significa
`queued`	Esperando a ser leído. Aún no se ha cobrado nada.
`processing`	Se está leyendo y convirtiendo en preguntas frecuentes en este momento.
`ready`	Finalizado. Sus preguntas frecuentes están en tu biblioteca.
`failed`	No se pudo importar. `error_message` indica el motivo.
`cancelled`	Detenido antes de ser leído (consulta Detener una importación).
`paused`	Detenido porque tu propia clave de IA falló durante la importación (consulta Reanudar una importación pausada).
`deleting`	Una eliminación masiva está procesándolo.
`unknown`	El registro no tiene estado. Considéralo como no preparado.

Adjuntar al importar. Pasa autoLinkToAgentId en cualquier endpoint de importación y la fuente —además de cada pregunta frecuente que produzca— se añadirá al conocimiento de ese agente en la misma llamada, sin necesidad de un paso de vinculación posterior. autoLinkToCampaignId hace lo mismo para una campaña clásica. La vinculación se realiza de la mejor manera posible: un ID que no existe o que pertenece a otra cuenta se omite silenciosamente y la importación continúa, así que confirma la vinculación leyendo el agente de nuevo.

Importar una página web

POST /kb-sources/url

Añade una página web a tu base de conocimientos.

Campos de la solicitud

Campo	Obligatorio	Descripción
`url`	Sí	Dirección `http` o `https` completa de la página.
`autoLinkToAgentId`	No	ID de un agente de IA al que adjuntar la fuente importada.
`autoLinkToCampaignId`	No	Legado. ID de una campaña a la que adjuntar la fuente importada.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Respuesta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Realice un sondeo a source_id con Comprobar una fuente hasta que el estado sea ready o failed.

Si la misma página ya se encuentra en su base de conocimientos, no se pone nada nuevo en cola y obtiene un 200 en su lugar; y si solicitó un enlace automático, la fuente existente se vinculará para usted de todos modos:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Un url faltante, o uno que no sea una dirección http/https válida, devuelve 400.

Importar un documento cargado

POST /kb-sources/file

Añade un documento que ya está en el almacenamiento de archivos de su cuenta como fuente de conocimiento. Tipos admitidos: PDF, DOCX, TXT, MD, CSV y XLSX.

Este endpoint no transporta el archivo. No hay carga multipart, ni cuerpo en base64, ni descarga desde una URL: usted envía la ubicación de almacenamiento de un archivo que ya existe, y debe residir en su propia carpeta de cargas (storage_path debe comenzar con users/{your user id}/uploads/) o la solicitud será rechazada con 403. El panel de control coloca los archivos allí cuando los arrastra. Si no tiene forma de colocar un archivo allí, importe una página web con Importar una página web en su lugar.

Campos de la solicitud

Campo	Obligatorio	Descripción
`storage_path`	Sí	Dónde reside el archivo cargado. Debe comenzar con `users/{your user id}/uploads/`.
`filename`	Sí	Nombre original del archivo incluyendo su extensión; así es como se detecta el tipo de archivo.
`mime_type`	Sí	Tipo MIME del archivo, por ejemplo `application/pdf`.
`autoLinkToAgentId`	No	ID de un agente de IA al que adjuntar el documento.
`autoLinkToCampaignId`	No	Legado. ID de una campaña a la que adjuntar el documento.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Respuesta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Estado	Cuándo
`400`	Falta un campo obligatorio o el archivo no es de un tipo que podamos leer.
`403`	`storage_path` está fuera de su propia carpeta de cargas.

Comprobar una fuente

GET /kb-sources/{sourceId}

El sondeo que sigue a cada importación y actualización. Repítalo hasta que el estado sea ready o failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Respuesta

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Campo	Tipo	Descripción
`status`	string	Dónde se encuentra la fuente en la canalización (consulte la tabla de estado).
`faq_count`	integer	Cuántas preguntas frecuentes se han generado a partir de esta fuente hasta el momento.
`section_count`	integer	En cuántas secciones de contenido se dividió la fuente.
`error_message`	string \| null	Por qué falló la importación, cuando el estado es `failed`. `null` en caso contrario.

Eliminar una fuente

DELETE /kb-sources/{sourceId}

Elimina una fuente de conocimiento. De forma predeterminada, las preguntas frecuentes que produjo se conservan; añada delete_faqs=true para eliminarlas también.

Parámetros de consulta

Parámetro	Requerido	Descripción
`delete_faqs`	No	Establézcalo en `true` para eliminar también todas las preguntas frecuentes que produjo esta fuente. El valor predeterminado es `false`.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted es 0 a menos que haya solicitado delete_faqs=true.

Importar muchas páginas a la vez

POST /kb-sources/bulk-import

Añade hasta 100 páginas web en una sola llamada; es el paso siguiente habitual a Descubrir páginas en un sitio web o Buscar nuevas páginas en un sitio web. Las páginas que ya están en su base de conocimiento se omiten en lugar de duplicarse (y siguen vinculadas al Agente cuando usted lo solicitó).

Campos de la solicitud

Campo	Requerido	Descripción
`urls`	Sí	Direcciones a importar. Al menos 1, como máximo 100 por llamada.
`autoLinkToAgentId`	No	ID de un Agente de IA al que adjuntar cada página importada.
`autoLinkToCampaignId`	No	Legado. ID de una campaña a la que adjuntar cada página importada.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Respuesta — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Consulte cada ID en queued_source_ids con Comprobar una fuente. Enviar una matriz urls vacía, una entrada que no sea una cadena o más de 100 entradas devuelve 400.

Eliminar muchas fuentes a la vez

POST /kb-sources/bulk-delete

Elimina hasta 2000 fuentes de conocimiento en una sola llamada. La eliminación se ejecuta en segundo plano y recibirá un correo electrónico cuando finalice.

La eliminación masiva también elimina las preguntas frecuentes. A diferencia de Eliminar una fuente, que las conserva a menos que solicite lo contrario, este endpoint elimina cada fuente junto con las preguntas frecuentes que produjo. No hay opción para conservarlas.

Campos de la solicitud

Campo	Obligatorio	Descripción
`sourceIds`	Sí	IDs de las fuentes a eliminar. Al menos 1, como máximo 2000 por llamada.
`domainLabel`	No	Un nombre descriptivo para esta limpieza. Se utiliza solo en el correo electrónico de finalización.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Respuesta — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Descubrir páginas en un sitio web

POST /kb-sources/discover-pages

Explora un sitio web desde una dirección inicial y enumera las páginas encontradas en el mismo dominio, cada una con una opinión sobre si vale la pena importarla. No se importa nada y no se selecciona nada por usted; este es el paso de “qué hay en este sitio” que ejecuta antes de decidir qué enviar a Importar muchas páginas a la vez.

Campos de la solicitud

Campo	Obligatorio	Descripción
`url`	Sí	Dirección desde la que comenzar a explorar, generalmente la página de inicio del sitio.
`maxPages`	No	Límite superior de cuántas páginas devolver.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Respuesta

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

Campo	Tipo	Descripción
`source_type`	string	Cómo se encontraron las páginas: `sitemap` (el mapa del sitio propio del sitio) o `link_discovery` (siguiendo enlaces).
`url`	string	Dirección completa de la página.
`title`	string \| null	Título de la página, cuando se pudo leer.
`depth`	integer	A cuántos enlaces de distancia de la página inicial se encontró esta página.
`score`	integer	Qué tan útil parece la página como conocimiento, de `0` a `100`.
`recommendation`	string	`add` (claramente vale la pena importar, puntuación 90 o superior), `maybe` (límite) o `skip` (contenido que rara vez ayuda a un asistente: registros de cambios, páginas legales, traducciones duplicadas).
`reason_key`	string	Una razón estable y legible por máquina detrás de la recomendación, por ejemplo `core_page`, `changelog_history`, `legal_page` o `locale_duplicate`.

La exploración es un esfuerzo de mejor intento. Si el sitio no se puede leer, la respuesta sigue siendo 200, con success: false, una lista pages vacía y un mensaje error. Compruebe success antes de leer pages.

Un url faltante devuelve 400.

Estimar cuánto costará una importación

POST /kb-sources/estimate-cost

Calcula cuántos créditos consumiría una importación propuesta, antes de comprometerse con ella. Las páginas se obtienen y los documentos se leen para medir su tamaño, pero no se importa nada y la estimación en sí no gasta créditos.

Campos de la solicitud

Campo	Obligatorio	Descripción
`urls`	No	Direcciones de página que está considerando importar.
`files`	No	Archivos ya cargados que está considerando. Cada entrada necesita `storage_path`, `filename` y `mime_type`.
`tier`	No	El nivel de calidad de IA en el que se ejecutará la importación, para que la estimación coincida con lo que realmente se le cobrará. Déjelo fuera para la tarifa estándar.

Envíe urls, files o ambos.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Respuesta

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}

Cada fila devuelve la URL o la ruta de almacenamiento en ref para que pueda hacerla coincidir con su entrada. Una página o archivo que no se pudo leer sigue obteniendo una fila, contada como un fragmento, con un error en ella.

Detener una importación

POST /kb-sources/cancel-import

Detiene las páginas que aún están esperando en la cola de importación: el botón “detener importación” para un rastreo que resultó ser más grande de lo que esperaba. Cancelar una página en espera no cuesta nada, porque aún no se ha leído.

Las páginas que ya se están procesando no se detienen: su trabajo está en curso y se cobra de todos modos, por lo que terminan. La respuesta informa cuántas fueron.

Campos de la solicitud

Campo	Requerido	Descripción
`host`	No	Solo detiene las páginas en espera en este sitio web (por ejemplo `docs.example.com`). Déjelo vacío para detener todas las importaciones en espera en la cuenta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Respuesta

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Reanudar una importación pausada

POST /kb-sources/resume-import

Reinicia una importación que se pausó porque su propia clave de IA dejó de funcionar.

Llamar a esto es su consentimiento para finalizar la importación con la clave que esté activa en ese momento, lo que puede significar gastar créditos de la plataforma si su propia clave sigue sin funcionar.

Campos de la solicitud

Campo	Requerido	Descripción
`host`	No	Solo reanuda las páginas pausadas en este sitio web. Déjelo vacío para reanudar todo lo que esté pausado.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta

{
  "success": true,
  "resumed": 58
}

Encontrar nuevas páginas en un sitio web

POST /kb-sources/refresh-domain

Explora un sitio web del que ya ha importado e informa solo de las páginas que aún no están en su base de conocimientos, cada una con la misma recomendación que el descubrimiento de páginas. No se importa nada y no se cambia nada.

Los dos seguimientos son llamadas deliberadamente separadas, por lo que abandonar esta no cuesta nada:

importe las páginas nuevas que desee con Importar muchas páginas a la vez;
vuelva a leer las páginas que ya tiene con Actualizar cada página de un sitio web.

Campos de la solicitud

Campo	Obligatorio	Descripción
`baseUrl`	Sí	Cualquier dirección del sitio web, o simplemente el host.
`maxPages`	No	Límite superior de cuántas páginas explorar.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Respuesta

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Campo	Tipo	Descripción
`discovered`	entero	Cuántas páginas se encontraron en el sitio en total.
`new_pages`	matriz	Páginas que aún no están en su base de conocimientos. No se pone nada en cola para usted: importe las que desee.
`new_urls_queued`	entero	Siempre `0`. Se mantiene por compatibilidad con versiones anteriores; este endpoint nunca pone nada en cola.
`existing_refresh_queued`	entero	Cuántas páginas que ya importó de este sitio se encontraron listas para ser leídas de nuevo. Esta llamada no pone nada en cola.
`batch_id`	cadena	Presente solo cuando se creó un lote.

Al igual que la detección, esto falla de forma controlada: un sitio que no se puede leer sigue devolviendo 200, con success: false, un new_pages vacío y un error. Un baseUrl faltante o vacío devuelve 400.

Actualizar cada página de un sitio web

POST /kb-sources/trigger-domain-refresh

Vuelve a leer cada página que ya ha importado de un sitio web, para que sus preguntas frecuentes sigan el contenido actual del sitio: las secciones modificadas se actualizan, las nuevas secciones se añaden y las secciones eliminadas se descartan.

Esto pone el trabajo en cola y devuelve una respuesta inmediatamente. Siga con Seguimiento de una actualización de sitio web y deténgalo con Detener una actualización de sitio web.

Campos de la solicitud

Campo	Obligatorio	Descripción
`baseUrl`	Sí	Cualquier dirección del sitio web, o simplemente el host.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Respuesta

{
  "success": true,
  "queued": 249
}

Seguimiento de una actualización de sitio web

GET /kb-sources/domain-refresh-status

El progreso de una actualización de sitio web, para que pueda mostrar el avance como “221 de 249”.

Parámetros de consulta

Parámetro	Obligatorio	Descripción
`baseUrl`	Sí	Cualquier dirección del sitio web, o simplemente el host.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job es null cuando no hay ninguna actualización ejecutándose para ese sitio web. Las páginas terminadas hasta el momento son total menos pending. El trabajo status es uno de refreshing (todavía procesando páginas), deduplicating (la pasada de limpieza al final), o el completed, failed y cancelled final. Guarde domainBatchId: es lo que debe pasar al endpoint de cancelación.

Un baseUrl faltante o vacío devuelve 400.

Detener una actualización de sitio web

POST /kb-sources/refresh-domain/cancel

Detiene una actualización de sitio web que aún está procesando sus páginas. Las páginas ya finalizadas mantienen su contenido actualizado; las páginas que no se han iniciado se descartan, y las páginas que se estaban volviendo a leer regresan a su estado anterior.

Campos de la solicitud

Campo	Obligatorio	Descripción
`jobId`	Sí	El `domainBatchId` devuelto por Rastrear una actualización de sitio web.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Respuesta

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Campo	Tipo	Descripción
`status`	string	Estado de la actualización después de esta llamada: `cancelled`, `deduplicating`, `completed` o `failed`.
`cancelled_units`	integer	Cuánto trabajo quedaba pendiente cuando se recibió la cancelación. `0` en una cancelación repetida.
`sources_reset`	integer	Páginas retiradas del procesamiento y devueltas a `ready`.
`sources_cancelled`	integer	Páginas nuevas de esta actualización que aún estaban en cola y ahora han sido canceladas.

Cancelar dos veces es inofensivo: la segunda llamada informa el mismo estado final. Una vez que la actualización ha pasado a su fase de limpieza, ya no se puede detener, y la respuesta devuelve success: false y reason: "already_finalizing". Un jobId faltante devuelve 400, y un trabajo que no está en su cuenta devuelve 404.

Actualizar una sola fuente

POST /kb-sources/{sourceId}/refresh

Vuelve a leer una página web que ya ha importado y sincroniza sus preguntas frecuentes con el contenido actual de la página: las secciones modificadas se actualizan, las nuevas se añaden y las eliminadas se descartan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Respuesta — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Consulte la fuente hasta que su estado deje de ser queued y processing. Un ID de fuente que no esté en su cuenta devuelve 404.

Elegir las páginas más relevantes

POST /kb-sources/select-relevant-pages

Solicita a la IA que elija las cinco páginas, de una lista de candidatas, que mejor describen un negocio; se utiliza al generar un manual de campaña a partir de un sitio web. Esto consume créditos.

Campos de la solicitud

Campo	Obligatorio	Descripción
`urls`	Sí	Direcciones de páginas candidatas para elegir, generalmente provenientes del descubrimiento de páginas.
`homeUrl`	Sí	La página de inicio del sitio, utilizada como contexto para la elección.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Respuesta

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Este es un asistente, no un recurso: en caso de error, sigue respondiendo 200, con success: false, una lista pages vacía y un mensaje error.

Grupos de conocimiento

Un grupo de conocimiento es un conjunto con nombre de preguntas frecuentes (FAQ) — “Envíos y devoluciones”, “Incorporación” — que puede aplicar a un agente o a una campaña en una sola llamada. El grupo contiene referencias, no copias: las preguntas frecuentes permanecen en su biblioteca única, por lo que editar una con la API de FAQ la actualiza en todos los lugares donde se utilice.

Aplicar un grupo solo añade lo que falta, por lo que aplicar el mismo grupo dos veces es inofensivo y added_count devuelve 0 la segunda vez.

Crear un grupo de conocimiento

POST /kb-groups

Crea un grupo. Comienza vacío: añádale preguntas frecuentes con Añadir una FAQ a un grupo.

Campos de la solicitud

Campo	Obligatorio	Descripción
`name`	Sí	Nombre del grupo.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Respuesta — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Cambiar el nombre de un grupo de conocimiento

PUT /kb-groups/{groupId}

Cambia el nombre de un grupo. Sus preguntas frecuentes permanecen intactas.

Campos de la solicitud

Campo	Obligatorio	Descripción
`name`	Sí	Nuevo nombre para el grupo.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Respuesta

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Eliminar un grupo de conocimiento

DELETE /kb-groups/{groupId}

Elimina el grupo. Solo se elimina el conjunto: las preguntas frecuentes que contiene permanecen en su biblioteca, y cualquier elemento al que ya se hubiera aplicado el grupo conservará esas preguntas frecuentes.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true
}

Añadir una FAQ a un grupo

POST /kb-groups/{groupId}/faqs

Coloca una FAQ existente en un grupo. Esto solo cambia el paquete; no adjunta la FAQ a ningún agente por sí solo; aplique el grupo para ello.

Campos de la solicitud

Campo	Obligatorio	Descripción
`faq_id`	Sí	ID de la FAQ a añadir.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Respuesta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Eliminar una FAQ de un grupo

DELETE /kb-groups/{groupId}/faqs/{faqId}

Saca una FAQ de un grupo. La FAQ en sí no se elimina, y los agentes a los que ya se había aplicado el grupo la conservan.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Aplicar un grupo a un agente

POST /kb-groups/{groupId}/apply-to-agent

Añade todas las FAQ del grupo al conocimiento de un agente de IA en una sola llamada: la forma rápida de dotar a un nuevo agente de un cuerpo de conocimiento que ya ha seleccionado.

Campos de la solicitud

Campo	Obligatorio	Descripción
`agent_id`	Sí	ID del agente de IA al que aplicar el grupo.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Respuesta

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count es cuántas FAQ se añadieron realmente; 0 cuando el grupo está vacío o ya se ha aplicado.

Aplicar un grupo a una campaña

POST /kb-groups/{groupId}/apply-to-campaign

La versión de campaña clásica de la llamada anterior. En una cuenta basada en agentes, utilice Aplicar un grupo a un agente en su lugar.

Campos de la solicitud

Campo	Obligatorio	Descripción
`campaign_id`	Sí	ID de la campaña a la que aplicar el grupo.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Respuesta

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Errores de la API de la base de conocimientos

Estos endpoints devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Estado	Cuándo ocurre en un endpoint de la base de conocimientos
`400`	Falta un campo obligatorio o no es válido: un `url` vacío, falta un `baseUrl` o `jobId`, más de 100 URL en una importación masiva, más de 2000 ID en una eliminación masiva o un tipo de archivo que no podemos leer.
`402`	No hay suficientes créditos para ejecutar la importación. Recargue e inténtelo de nuevo.
`403`	Un `storage_path` fuera de su propia carpeta de cargas, o su plan no incluye acceso a la API.
`404`	No se encontró la fuente, el grupo, las preguntas frecuentes (FAQ), el agente, la campaña o el trabajo de actualización; o bien no existe o pertenece a otra cuenta.

Los fallos leves no son errores. La detección (discover-pages, refresh-domain) y el asistente de selección de páginas responden 200 con success: false y un mensaje error cuando no se puede leer el sitio web, en lugar de fallar la solicitud. Compruebe siempre success antes de leer los datos.

Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Relacionado

API de preguntas frecuentes: lea, edite y vincule las preguntas frecuentes que generan sus fuentes.
Gestión de preguntas frecuentes: la misma base de conocimientos en el panel de control.
Agentes de IA: los agentes a los que adjunta fuentes y grupos.
Acceso a la API: genere su clave de API.
Autenticación: todas las formas de enviar su clave.

API de la base de conocimientos #

Cómo funciona una importación #

Importar una página web #

Importar un documento cargado #

Comprobar una fuente #

Eliminar una fuente #

Importar muchas páginas a la vez #

Eliminar muchas fuentes a la vez #

Descubrir páginas en un sitio web #

Estimar cuánto costará una importación #

Detener una importación #

Reanudar una importación pausada #

Encontrar nuevas páginas en un sitio web #

Actualizar cada página de un sitio web #

Seguimiento de una actualización de sitio web #

Detener una actualización de sitio web #

Actualizar una sola fuente #

Elegir las páginas más relevantes #

Grupos de conocimiento #

Crear un grupo de conocimiento #

Cambiar el nombre de un grupo de conocimiento #

Eliminar un grupo de conocimiento #

Añadir una FAQ a un grupo #

Eliminar una FAQ de un grupo #

Aplicar un grupo a un agente #

Aplicar un grupo a una campaña #

Errores de la API de la base de conocimientos #

Relacionado #

API de la base de conocimientos

Cómo funciona una importación

Importar una página web

Importar un documento cargado

Comprobar una fuente

Eliminar una fuente

Importar muchas páginas a la vez

Eliminar muchas fuentes a la vez

Descubrir páginas en un sitio web

Estimar cuánto costará una importación

Detener una importación

Reanudar una importación pausada

Encontrar nuevas páginas en un sitio web

Actualizar cada página de un sitio web

Seguimiento de una actualización de sitio web

Detener una actualización de sitio web

Actualizar una sola fuente

Elegir las páginas más relevantes

Grupos de conocimiento

Crear un grupo de conocimiento

Cambiar el nombre de un grupo de conocimiento

Eliminar un grupo de conocimiento

Añadir una FAQ a un grupo

Eliminar una FAQ de un grupo

Aplicar un grupo a un agente

Aplicar un grupo a una campaña

Errores de la API de la base de conocimientos

Relacionado