Txt-to-JSON · Modo agente
Txt / HTML / XML a JSON con Modo agente
Endpoint
https://www.claix.dev/agent/txt-jsonModo agente activo
Este endpoint ejecuta primero la extracción estructurada del schema principal y después una fase de razonamiento con agent_definition. La respuesta incluye data[] (extracción) y agent_data (inferencia tipada). El schema debe tener is_agent_mode activado.
Este endpoint recibe un campo content con texto plano, HTML o XML ya procesado y devuelve un único objeto JSON con los datos extraídos, siguiendo exactamente la estructura de un schema de tipo txt-json.
A diferencia de doc-json, aquí no se sube ningún archivo: el contenido llega listo en el formulario multipart. El resto del flujo (API key, schema, logs, ventana de contexto opcional) es idéntico al resto de funciones hijas.
URLs públicas (dominio Claix): extracción en POST https://www.claix.dev/api/txt-json; Modo agente en POST https://www.claix.dev/agent/txt-json. Nunca expongas la URL directa de Supabase al cliente final.
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 de usuario.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
Si envías los dos, el header x-api-key tiene prioridad.
Antes de procesar el contenido, el sistema valida que la API key exista y esté activa, y que la cuenta no esté suspendida. Si falla, responde 401.
2. Formato de la petición
Método HTTP: POST · Content-Type: multipart/form-data (obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| content | Texto | Sí | El texto, HTML o XML a transformar. No es un archivo: es el contenido en sí, enviado como parte de texto del formulario. |
| schema_id | Texto (UUID) | Sí | Identificador de un schema de tipo txt-json previamente creado en tu cuenta. |
El nombre de campo debe ser exactamente content, y el del identificador del schema exactamente schema_id.
Requisito importante sobre el schema
El schema_id debe corresponder a un schema de tipo txt-json. Si envías un schema de otro tipo (pdf-json, doc-json, etc.), la petición se rechaza con 400.
Tipos de contenido admitidos en content
| Tipo | Ejemplos de uso | Notas |
|---|---|---|
| Texto plano | Emails en bruto, logs, contratos pegados, CSV textual, Markdown sin renderizar | Se analiza tal cual; no se interpreta sintaxis Markdown. |
| HTML | Páginas web, fragmentos de DOM, emails HTML, facturas renderizadas | El modelo lee etiquetas y texto visible; no ejecuta JavaScript. |
| XML | Feeds RSS/Atom, SOAP, facturas electrónicas, respuestas de APIs legacy | Se respeta la estructura de nodos para localizar datos. |
Requisitos del contenido
- El contenido no puede estar vacío (solo espacios).
- Máximo 300.000 caracteres. Si se supera, la petición se rechaza con 413 antes de llamar a la IA.
- Como respaldo, el campo
contenttambién acepta unFilede texto si tu cliente lo envía así, pero lo habitual es un string en el multipart.
3. Cómo construir la llamada paso a paso
- Ten a mano tu API key.
- Crea un schema de tipo
txt-jsony copia suschema_id. - Construye una petición POST a https://www.claix.dev/agent/txt-json.
- Añade el header de autenticación (
x-api-keyoAuthorization: Bearer). - Construye el cuerpo como
multipart/form-dataconcontent(texto/HTML/XML) yschema_id(UUID como string). - Envía la petición y comprueba que el código HTTP sea 200.
4. Ejemplos de llamada
Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
{
"success": true,
"schema_utilizado": "Contratos legales",
"total_registros": 1,
"data": [
{
"parte_a": "Inmobiliaria Norte S.L.",
"parte_b": "Carlos Méndez",
"fecha_firma": "2026-03-01"
}
],
"agent_data": {
"clausula_penalizacion": true,
"tipo_renovacion": "automatica",
"resumen_contrato": "Arrendamiento con renovación automática y cláusula de penalización por impago."
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado en la extracción. |
| total_registros | number | Número de registros en data. |
| data | array | Objetos extraídos según el schema principal (igual que en extracción). |
| agent_data | object | Respuestas tipadas del Modo Agente según agent_definition (booleanos, números, strings). |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Falta content o schema_id, el body no es multipart, el contenido está vacío, o el schema no es de tipo txt-json.
401 — API key ausente, inválida, desactivada o cuenta no activa.
404 — El schema_id no existe o no pertenece a la cuenta.
413 — El contenido supera 300.000 caracteres.
422 — No se pudo extraer ningún dato relacionado con tu schema.
502 — Fallo del servicio de IA. 405 — Método distinto de POST. 500 — Error interno.
7. 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 |