Multi-Document
Preguntar a varios documentos
Endpoint
https://claix.dev/multi-documentEnvía hasta 10 archivos en una sola llamada, junto con las mismas preguntas tipadas que Consultar espacio. Cada archivo se convierte a Markdown y las respuestas se construyen cruzando esos textos. No hay schema_id y los archivos no tienen que estar guardados de antemano.
Los formatos admitidos son los mismos que Extracción → Markdown: PDF, Excel/CSV, Word y texto, HTML/XML, imágenes y audio. Si un archivo no se puede convertir, falla la petición entera y no se devuelve ninguna respuesta.
Está pensado para integraciones server-to-server (backends, scripts, n8n, Zapier, Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.
1. Autenticación
Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión, y debe tratarse con el mismo cuidado que una contraseña de base de datos.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.
Antes de procesar los archivos, el sistema valida que:
- La API key exista y esté activa.
- La cuenta asociada esté activa (no suspendida).
Si falla, se rechaza con 401 sin procesar los archivos.
2. Formato de la petición
Método: POST · Content-Type: multipart/form-data
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | Repite el campo de 1 a 10 veces. También se aceptan files y documents. Mismos formatos y límites de tamaño que Extracción → Markdown. |
| questions | Texto JSON | Sí | Array de { question, format }. Máximo 5 preguntas, 400 caracteres cada una. format: string | int | boolean | timestamp | array. |
| window_context | Booleano | No | true conserva cada documento convertido. Si no viene, o es false, solo se responden las preguntas. |
| window_time | Número o texto | Obligatorio si window_context es true | Minutos: 5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440, o infinity. infinity exige el modo persistente activo en la cuenta. |
| space_id | Texto (UUID) | No | Espacio de conocimiento del dueño de la API key. Solo si window_context es true. Los documentos conservados se asocian a ese espacio. |
3. Cómo construir la llamada
- Ten a mano tu API key. No necesitas schema_id.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-datacon 1 a 10 camposfiley un JSONquestions. - Para conservar los documentos, envía también
window_context=trueywindow_time.space_ides opcional y solo aplica en ese caso. - Comprueba el código HTTP: solo 200 indica éxito. Después lee ia_response.
4. Ejemplos de llamada
Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n. Puedes cambiar el lenguaje con el selector y copiar el código. «Conservar los documentos» añade window_context, window_time y space_id.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
Las respuestas quedan alineadas con las preguntas y usan el format pedido, o null si el dato no está en los archivos. Si la verificación de fuente está activada en la consulta a espacios de conocimiento, cada respuesta es { value, source }.
{
"user_ask": [
{ "question": "¿Qué proveedor factura más en total?", "format": "string" },
{ "question": "¿El importe del contrato coincide con la factura?", "format": "boolean" }
],
"ia_response": [
"Suministros Omega S.A.",
true
],
"documents_processed": 2,
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}Si window_context es true, los archivos convertidos se conservan y sus ids aparecen en esa llamada dentro del panel de logs. No son un campo extra de este JSON. Si no los conservas, el panel indica que no se guardaron.
| Campo | Tipo | Descripción |
|---|---|---|
| user_ask | array | Las preguntas respondidas, en el mismo orden en que se enviaron. |
| ia_response | array | Una respuesta por pregunta, en el format pedido, o null si los archivos no contienen el dato. |
| documents_processed | number | Cuántos archivos se convirtieron y se usaron para responder. |
| log_id | string (UUID) | Identifica la llamada en el panel de logs. |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos).",
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}400 — Falta questions, está vacío, tiene más de 5 ítems, una pregunta supera 400 caracteres, o un format no es string, int, boolean, timestamp o array. También: no hay archivos, hay más de 10, un formato no está soportado, window_time no es válido, space_id llega sin window_context, o infinity llega sin el modo persistente activo.
401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.
404 — space_id no existe en esta cuenta.
413 — Un archivo supera el límite de tamaño de su formato.
422 — Un archivo no pudo convertirse en Markdown legible. Falla la petición entera.
502 — Fallo del servicio de IA (transitorio; reintenta con backoff).
405 — Método distinto de POST. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (documento o datos mal formados) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 404 | Recurso no encontrado | No, corrige el schema_id primero |
| 405 | Método HTTP incorrecto | No, corrige el método primero |
| 413 | Archivo o texto extraído demasiado grande | No, reduce el tamaño primero |
| 422 | Sin datos extraíbles | No, revisa el documento/schema primero |
| 500 | Error interno del servidor | Sí, con precaución |
| 502 | Fallo del servicio de IA | Sí, recomendado con backoff |
8. Buenas prácticas
- Valida el código HTTP antes de leer ia_response.
- No pases de 5 preguntas ni de 10 archivos. Una conversión fallida rechaza la llamada entera.
- Los ids de los documentos conservados aparecen en el panel de logs solo si window_context es true. Si lo omites, los archivos no se guardan.
- Reintenta automáticamente solo en 500 y 502, nunca en 4xx salvo cambios en la petición.
- No incluyas tu API key en frontend ni repositorios públicos.