Fuentes y entrenamiento de la API v2

Lista y crea fuentes de agentes, sube archivos directamente al almacenamiento, elimina documentos, revisa el estado del entrenamiento e inicia el reentrenamiento de fuentes web.

Usa estos endpoints para administrar fuentes de texto, preguntas y respuestas, URL y archivos, y para reentrenar las fuentes web indexadas. Todos los endpoints de esta página requieren Authorization: Bearer YOUR_API_KEY y acceso a {agentId}.

Consulta el catálogo de errores para conocer los errores compartidos de autenticación, validación, cuota y recursos.

Objeto de fuente

Campo	Tipo	Notas
`id`	string	ID del documento.
`title`	string	Título de la fuente.
`sourceType`	string	Tipo de fuente almacenado, incluidos `web_crawl`, `file_upload`, `text_snippet` o `qna_entry`.
`createdAt`	integer o null	Marca de tiempo Unix en segundos.
`lastCrawledAt`	integer o null	Marca de tiempo Unix en segundos.
`sourceMetadata`	any JSON value	Metadatos de fuente almacenados.

Listar fuentes

Ruta: /api/v2/agents/{agentId}/sources

GET /api/v2/agents/{agentId}/sources

Autenticación: Clave de API bearer con acceso a {agentId}.

Query	Requerido	Restricciones
`limit`	No	Número entero de 1 a 100; el valor predeterminado es 20.
`cursor`	No	Cursor opaco devuelto por la página anterior. Reenvíalo sin modificarlo.
`sourceType`	No	`web_crawl`, `file_upload`, `text_snippet` o `qna_entry`.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources?sourceType=text_snippet&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Éxito: 200 OK

{
  "data": [
    {
      "id": "41b4c1d3-887d-46a5-95ae-c761922c6bc7",
      "title": "Refund policy",
      "sourceType": "text_snippet",
      "createdAt": 1784332800,
      "lastCrawledAt": null,
      "sourceMetadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Los límites, cursores y tipos de fuente inválidos devuelven 400 VALIDATION_INVALID_BODY.

Agregar una fuente de texto

Ruta: /api/v2/agents/{agentId}/sources/text

POST /api/v2/agents/{agentId}/sources/text

Autenticación: Clave de API bearer con acceso a {agentId}.

Campo del cuerpo	Requerido	Tipo y restricciones
`title`	Sí	String de 1 a 200 caracteres antes de recortar; el valor aceptado se recorta.
`content`	Sí	String no vacío, de no más de 262.144 bytes UTF-8 (256 KB), y que no contenga solo espacios en blanco.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/text' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refund policy","content":"Refunds are available within 30 days."}'

Éxito: 201 Created

{
  "documentId": "41b4c1d3-887d-46a5-95ae-c761922c6bc7"
}

Una entrada inválida o un fallo de procesamiento que no sea de almacenamiento devuelve 400 VALIDATION_INVALID_BODY. Un fallo de procesamiento por límite de almacenamiento devuelve 403 QUOTA_STORAGE_LIMIT.

Agregar una fuente de preguntas y respuestas

Ruta: /api/v2/agents/{agentId}/sources/qna

POST /api/v2/agents/{agentId}/sources/qna

Autenticación: Clave de API bearer con acceso a {agentId}.

Campo del cuerpo	Requerido	Tipo y restricciones
`title`	Sí	String de 1 a 200 caracteres antes de recortar; el valor aceptado se recorta.
`questions`	Sí	Array de máximo 10 strings, cada uno de máximo 500 caracteres. Al menos una entrada debe contener un carácter que no sea de espacio en blanco.
`answer`	Sí	String no vacío, de no más de 262.144 bytes UTF-8 (256 KB), y que no contenga solo espacios en blanco.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/qna' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Shipping time","questions":["How long does shipping take?","When will my order arrive?"],"answer":"Standard shipping takes 3–5 business days."}'

Éxito: 201 Created

{
  "documentId": "531a3fbe-40c2-4d22-a524-1f4a70f509f1"
}

Agregar o reentrenar una fuente de URL

Ruta: /api/v2/agents/{agentId}/sources/url

POST /api/v2/agents/{agentId}/sources/url

Autenticación: Clave de API bearer con acceso a {agentId}.

Campo del cuerpo	Requerido	Tipo y restricciones
`url`	Sí	URL HTTP o HTTPS no vacía, con un dominio. Si falta el protocolo, se normaliza a `https://`. Se rechazan los rangos loopback, privados, link-local, unique-local, reservados, las variantes de localhost, los TLD internos y los nombres de host de una sola etiqueta.

Enviar una URL ya indexada para el agente crea un trabajo de reentrenamiento. Una URL nueva primero verifica la capacidad de almacenamiento. Las URL de video también requieren acceso al plan de transcripción de video.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://docs.example.com/getting-started"}'

Éxito: 202 Accepted

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "isRetrain": false
}

Una entrada inválida devuelve 400 VALIDATION_INVALID_BODY. La falta de acceso a la transcripción de video devuelve 403 SUBSCRIPTION_API_RESTRICTED_PLAN; los fallos de cuota de almacenamiento o de cola devuelven 403 QUOTA_STORAGE_LIMIT; un fallo en la creación del trabajo que no sea de cuota devuelve 500 INTERNAL_SERVER_ERROR.

Agregar fuentes de archivo con URL de carga firmadas

Las fuentes de archivo usan un flujo de API en dos pasos, de modo que los bytes del archivo viajan directamente desde tu cliente al almacenamiento privado en lugar de pasar por la ruta de la API. Cada archivo puede pesar como máximo 50 MB, y una solicitud puede contener como máximo 20 archivos. Las extensiones admitidas son .pdf, .txt, .md, .docx, .xlsx y .pptx.

1. Crear URL de carga firmadas

Ruta: /api/v2/agents/{agentId}/sources/file/upload-url

POST /api/v2/agents/{agentId}/sources/file/upload-url

Envía los nombres de archivo originales:

{
  "files": [
    { "fileName": "product-guide.pdf" },
    { "fileName": "faq.md" }
  ]
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/file/upload-url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"fileName":"product-guide.pdf"},{"fileName":"faq.md"}]}'

Éxito: 200 OK

{
  "files": [
    {
      "fileName": "product-guide.pdf",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    },
    {
      "fileName": "faq.md",
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "uploadUrl": "https://storage.example.com/storage/v1/object/upload/sign/training_files/chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md?token=SIGNED_TOKEN",
      "token": "SIGNED_TOKEN"
    }
  ]
}

2. Subir los bytes del archivo

Sube cada archivo directamente a su uploadUrl con PUT:

await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': file.type },
  body: file,
});

Cuando uses el cliente de JavaScript de Supabase, pasa la ruta y el token correspondientes del paso 1:

await supabase.storage
  .from('training_files')
  .uploadToSignedUrl(storagePath, token, file);

No cambies ni construyas las rutas de almacenamiento por tu cuenta. El registro solo acepta rutas devueltas para este agente en el paso 1.

3. Registrar los archivos subidos

Ruta: /api/v2/agents/{agentId}/sources/file

POST /api/v2/agents/{agentId}/sources/file

Después de que cada carga directa se complete, registra las rutas devueltas con sus nombres de archivo originales:

{
  "files": [
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/V1StGXR8_Z5jdHi6-product-guide.pdf",
      "fileName": "product-guide.pdf"
    },
    {
      "storagePath": "chatbot-955f28f1-8515-40bb-802c-f3f730bf0343/N5jFt4Z9kSC3vHqA-faq.md",
      "fileName": "faq.md"
    }
  ]
}

Éxito: 202 Accepted

{
  "jobId": 321,
  "fileCount": 2
}

El registro verifica que cada objeto exista, no esté vacío, no supere los 50 MB y pertenezca al agente solicitado antes de iniciar el trabajo de procesamiento. Las cargas inválidas o faltantes devuelven 400 VALIDATION_INVALID_BODY; una denegación por cuota de almacenamiento devuelve 403 QUOTA_STORAGE_LIMIT; los fallos de almacenamiento o de cola devuelven 500 INTERNAL_SERVER_ERROR.

Eliminar una fuente

Ruta: /api/v2/agents/{agentId}/sources/{documentId}

DELETE /api/v2/agents/{agentId}/sources/{documentId}

Autenticación: Clave de API bearer con acceso a {agentId}.

{documentId} debe ser un UUID devuelto por una respuesta de creación o listado de fuentes.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/sources/41b4c1d3-887d-46a5-95ae-c761922c6bc7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Éxito: 200 OK

{
  "deleted": true
}

Un UUID inválido devuelve 400 VALIDATION_INVALID_BODY. Un UUID válido que no identifica ningún documento del agente devuelve 404 RESOURCE_DOCUMENT_NOT_FOUND.

Obtener el estado del entrenamiento

Ruta: /api/v2/agents/{agentId}/train

GET /api/v2/agents/{agentId}/train

Autenticación: Clave de API bearer con acceso a {agentId}.

Éxito: 200 OK, con un objeto de estado simple.

Campo	Tipo	Notas
`status`	string	`training` cuando existe un trabajo pendiente o en ejecución; de lo contrario, `trained` cuando existe una marca de tiempo del último entrenamiento; de lo contrario, `idle`.
`documentCount`	integer	Cantidad de documentos de fuente del agente.
`lastTrainedAt`	integer o null	Marca de tiempo Unix en segundos.
`activeJob`	object o null	Trabajo pendiente o en ejecución más reciente.
`activeJob.id`	string	ID del trabajo.
`activeJob.status`	string	Estado del trabajo almacenado.
`activeJob.tasksCount`	integer	Cantidad total de tareas.
`activeJob.tasksCompletedCount`	integer	Cantidad de tareas completadas.
`activeJob.createdAt`	integer o null	Marca de tiempo Unix en segundos.

{
  "status": "training",
  "documentCount": 12,
  "lastTrainedAt": 1784246400,
  "activeJob": {
    "id": "c3c61f67-70fe-42da-a843-24112ded8aeb",
    "status": "running",
    "tasksCount": 8,
    "tasksCompletedCount": 3,
    "createdAt": 1784332800
  }
}

Iniciar el reentrenamiento de fuentes web

POST /api/v2/agents/{agentId}/train

Autenticación: Clave de API bearer con acceso a {agentId}. Este endpoint no requiere cuerpo de solicitud.

El endpoint reentrena las URL web indexadas, no las fuentes de texto, preguntas y respuestas, ni las de archivos subidos.

Cuando existe al menos una URL indexada, el éxito es 202 Accepted:

{
  "jobId": "c3c61f67-70fe-42da-a843-24112ded8aeb",
  "count": 8,
  "message": "Retraining started for 8 URLs"
}

Cuando no existe ninguna URL indexada, el éxito es 200 OK y no se crea ningún trabajo:

{
  "jobId": null,
  "count": 0,
  "message": "No web sources to retrain"
}

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/train' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Fuentes y entrenamiento de la API v2

Lista y crea fuentes de agentes, sube archivos directamente al almacenamiento, elimina documentos, revisa el estado del entrenamiento e inicia el reentrenamiento de fuentes web.

Objeto de fuente

Listar fuentes

Agregar una fuente de texto

Agregar una fuente de preguntas y respuestas

Agregar o reentrenar una fuente de URL

Agregar fuentes de archivo con URL de carga firmadas

1. Crear URL de carga firmadas

2. Subir los bytes del archivo

3. Registrar los archivos subidos

Eliminar una fuente

Obtener el estado del entrenamiento

Iniciar el reentrenamiento de fuentes web

Referencia relacionada