Claix es una API de inteligencia documental con IA que convierte archivos no estructurados en JSON basado en schemas y ofrece contexto documental consultable para agentes de IA. Procesa PDFs, hojas Excel, documentos Word, imágenes y texto con modelos multimodales de visión, para que los desarrolladores extraigan datos estructurados y consulten documentos bajo demanda.

¿Qué formatos de archivo puedo convertir a JSON estructurado?

Claix admite de forma nativa PDF (.pdf), hojas Excel (.xlsx, .xls), documentos Word (.docx, .doc), imágenes (.png, .jpg, .jpeg, .webp) y texto plano (.txt, .html, .md). Cada formato se procesa con comprensión visual del documento y devuelve JSON tipado y validado conforme a tu schema personalizado.

¿Cómo convierto hojas Excel a JSON con la API?

Para convertir un Excel, envía un POST a /api/excel-json con tu archivo y el schema JSON de destino. Claix interpreta libros con varias hojas, cabeceras fusionadas y tablas relacionales, y devuelve JSON limpio listo para ingestión.

¿Puedo convertir PDFs, documentos Word e imágenes a JSON?

Sí. Claix ofrece endpoints dedicados para cada formato: /api/pdf-json para PDFs complejos o escaneados, /api/doc-json para Word e /api/img-json para imágenes y recibos. Cada endpoint usa inteligencia visual para interpretar el layout y devolver JSON válido.

¿Para quién está pensada Claix?

Claix está diseñada para desarrolladores de software, constructores de agentes de IA, equipos de ingeniería SaaS y especialistas en automatización con plataformas como n8n o Make. Elimina la necesidad de montar pipelines propios de OCR, chunking y recuperación vectorial.

¿Cuál es el modelo de precios de Claix?

Claix funciona con un modelo de pago por uso por documento procesado (desde 0,10 € en imágenes hasta 0,15 € en PDFs complejos) y 0,03 € por pregunta de seguimiento. No hay suscripción mensual obligatoria para la extracción estándar, y las cuentas nuevas incluyen 100 procesamientos exitosos gratis.

¿Se cobran las peticiones fallidas?

No. Claix solo cobra las peticiones de procesamiento con HTTP 200 que devuelven datos extraídos válidos. Las llamadas fallidas por parámetros inválidos o errores del sistema no consumen tu cuota ni tu saldo.

¿Qué es el Modo Agente de Claix?

El Modo Agente de Claix (/agent/*-json) es un modo de extracción en el que un agente de IA interpreta documentos ambiguos con instrucciones en lenguaje natural en lugar de un schema rígido, permitiendo una extracción dinámica según el contexto.

¿Qué diferencia hay entre la extracción normal y el Modo Agente?

La extracción normal impone conformidad estricta y determinista al schema para pipelines predecibles. El Modo Agente permite razonar en lenguaje natural sobre el contenido del documento, ideal para contratos no estructurados y layouts variables.

¿Cómo hago preguntas de seguimiento a un solo documento?

Cuando procesas un documento con la ventana de contexto activada, Claix te devuelve un document_id. Puedes enviar preguntas a POST /document-context/{document_id} para consultar ese archivo concreto sin volver a subirlo ni reprocesarlo.

¿Qué es la ventana de contexto temporal?

La ventana de contexto es una capa de retención temporal que mantiene un documento procesado consultable para preguntas de seguimiento sin almacenamiento permanente, permitiendo interacciones multi-turno del agente antes de expirar automáticamente.

¿Qué son los Espacios de Conocimiento y cómo consulto varios documentos a la vez?

Los Espacios de Conocimiento te permiten agrupar varios documentos persistentes bajo un único space_id. Al enviar preguntas a POST /space-context/{space_id}, tu agente de IA puede consultar, comparar, calcular totales y cruzar datos entre todos los documentos activos de ese espacio a la vez.

¿Puedo usar Claix como marca blanca o integrarlo en flujos automatizados?

Sí. Claix es totalmente headless e integra servidor a servidor mediante API keys, por lo que encaja en backends SaaS propios y en plataformas de automatización como n8n o Make.

Ventana de Contexto

Consultar un espacio de conocimiento

Endpoint

POSThttps://claix.dev/space-context/{space_id}

Los documentos persistidos se pueden agrupar en espacios de conocimiento. Este endpoint responde preguntas usando todos los documentos de un espacio a la vez, en lugar de uno solo, para que puedas comparar, sumar o cuadrar datos repartidos entre varios archivos.

Es el hermano de POST /document-context/{document_id}: la entrada y la salida son exactamente iguales. Lo único que cambia es el alcance de la respuesta y que en la URL viaja un space_id en vez de un document_id.

URL pública: POST https://claix.dev/space-context/{space_id}. Nunca expongas la URL directa de Supabase.

Está pensado para integraciones server-to-server. Requiere API key secreta.

1. Autenticación

Toda petición debe incluir tu API key.

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

El sistema valida que la key exista y esté activa, y que la cuenta no esté suspendida. Si falla, responde 401.

2. Cómo se agrupan los documentos

Antes de poder preguntar a un espacio, los documentos tienen que estar dentro de él. Para eso, las cinco llamadas de extracción (/api/excel-json, /api/pdf-json, /api/doc-json, /api/img-json, /api/txt-json) y las cinco de Modo agente (/agent/*-json) aceptan un campo opcional space_id.

El espacio debe pertenecer a la misma cuenta dueña de la API key. Si no existe o es de otra cuenta, la extracción responde 404.
Solo tiene efecto cuando el schema tiene la ventana de contexto activada, que es cuando el documento se guarda. Sin ella no hay nada que agrupar.
Puedes reutilizar el mismo space_id en tantas extracciones como quieras: cada documento se suma al espacio.

Consulta el panel de la derecha, pestaña Agrupar al extraer, para ver el flujo completo: extraer con space_id y después preguntar al espacio.

3. Formato de la petición

Método HTTP: POST · Content-Type: application/json

El space_id (UUID) forma parte de la ruta. El body es idéntico al de document-context y tiene un único campo:

Campo	Tipo	Obligatorio	Descripción
questions	array de strings	Sí	Preguntas a responder usando solo el contenido de los documentos del espacio. Máximo 5 por turno. Máximo 400 caracteres por pregunta.

{
  "questions": [
    "¿Qué proveedor factura más en total sumando todas las facturas?",
    "¿Hay algún contrato cuyo importe no coincida con su factura?"
  ]
}

Al menos 1 pregunta; máximo 5.
Cada string debe tener contenido (no solo espacios).
El espacio debe pertenecer a la cuenta de la API key y contener al menos un documento vigente.

4. Límites del contexto

Un espacio puede crecer sin parar, así que la llamada acota cuánta información recibe la IA. Esto mantiene el coste bajo control y evita que la precisión se degrade cuando hay demasiado texto en juego.

Límite	Valor	Qué ocurre al superarlo
Documentos por consulta	50	Se usan los 50 más recientes del espacio.
Caracteres de contexto en total	200.000	El presupuesto se reparte entre los documentos seleccionados, así que ninguno queda fuera del todo.
Preguntas por llamada	5	Responde 400. Divide las preguntas en varias llamadas.

Los documentos caducados no se incluyen: si un documento ya expiró, deja de contar para el espacio.
Cuando un documento se recorta por presupuesto, la IA lo sabe y no afirma nada sobre la parte que no ha visto.
Si el espacio existe pero no tiene ningún documento vigente con contenido, responde 400.

5. Cómo construir la llamada

Crea un espacio de conocimiento en el panel y copia su space_id.
Extrae tus documentos con la ventana de contexto activa, enviando ese space_id en cada llamada.
Ten a mano tu API key.
POST a https://claix.dev/space-context/{space_id}.
Envía { "questions": ["..."] } como JSON.
Comprueba HTTP 200 y lee ia_response.

6. Ejemplos de llamada

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.

7. Formato de la respuesta exitosa

Código de estado: 200 OK · Content-Type: application/json

La forma es idéntica a la de document-context, para que puedas cambiar de una llamada a otra sin tocar el código que lee la respuesta.

{
  "user_ask": [
    "¿Qué proveedor factura más en total sumando todas las facturas?",
    "¿Hay algún contrato cuyo importe no coincida con su factura?"
  ],
  "ia_response": [
    "Suministros Omega S.A., 48.320 € entre tres facturas (febrero, marzo y abril).",
    "Sí: contrato-omega.pdf fija 12.000 € y factura-omega-03.pdf cobra 13.450 €."
  ]
}

Campo	Tipo	Descripción
user_ask	array de strings	Las preguntas enviadas, en el mismo orden.
ia_response	array de string o null	Respuestas alineadas 1:1 con user_ask. Si el dato no está en ninguno de los documentos del espacio, el valor es null (JSON nativo, no un texto). Cuando la respuesta sale de cruzar varios documentos, cita brevemente de qué archivos procede.

8. Códigos de error

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos)."
}

400 — space_id inválido, JSON mal formado, questions ausente, vacío, más de 5 ítems, una pregunta supera 400 caracteres, o el espacio no tiene documentos vigentes con contenido.

401 — API key ausente, inválida, desactivada o cuenta no activa.

404 — El espacio no existe o no pertenece a la cuenta.

502 — Fallo del servicio de IA. 405 — Método distinto de POST. 500 — Error interno.

9. Resumen rápido de códigos de error

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