ClaixClaixEN

Documentación API

Endpoints de schemas

Consulta, obtén, crea, actualiza y elimina schemas de tu cuenta con la misma API key de extracción.

Schemas · Actualizar

Actualizar un schema por API

Endpoint

PUThttps://claix.dev/api/update-schema/{schema_id}

Sustituye la configuración completa de un schema existente (mismo cuerpo que POST /api/create-schema). El schema_id va en la URL; el body lleva name, type, schema_definition y opciones.

Llama siempre a https://claix.dev/api/update-schema/{schema_id}. También se admite POST.

Está pensado para integraciones server-to-server. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión.

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.

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

2. Formato de la petición

Método: PUT (también se admite POST) · Content-Type: application/json · Path: schema_id (UUID)

CampoTipoObligatorioDescripción
schema_iduuidSí (URL)Identificador del schema a actualizar.
namestringSíNombre visible del schema (máx. 200).
typestringSíexcel-json, json-excel, pdf-json, doc-json, img-json, txt-json o audio-json.
schema_definitionobjetoSíCampos a extraer. Cada clave es el nombre JSON de salida.
is_agent_modebooleanNoActiva Modo Agente. Si omites el campo pero envías agent_definition, se asume true.
agent_definitionobjetoSi hay modo agenteParámetros a razonar. Obligatorio si is_agent_mode es true.
resumen_agentstringNoInstrucción extra para la fase agente (máx. 500).
window_contextbooleanNoActiva la ventana temporal de contexto. Por defecto false.
window_timenumber | stringSi window_context es trueDuración de la ventana en minutos (5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440) o la cadena "infinity" para ventana sin caducidad. infinity requiere modo persistente activo en la cuenta; se guarda como window_time 0.
cita_por_campobooleanNoActiva la verificación de fuente: vincula cada campo extraído con su ubicación en el documento original y comprueba que el valor aparece en el contenido. Por defecto false.

Cada campo de schema_definition debe ser:

{
  "nombre_dni": {
    "type": "string",
    "description": "nombre de la persona del dni"
  }
}

Types permitidos en extracción: string, integer, number, boolean. La description es obligatoria.

Cada parámetro de agent_definition usa boolean, string, closed o integer. Si el type es closed, options debe ser un array con al menos una respuesta.

El tipo json-excel no admite Modo Agente.

3. Cómo construir la llamada

  1. Obtén el schema_id con GET /api/schemas o GET /api/get-schema/{schema_id}.
  2. Construye un PUT JSON a https://claix.dev/api/update-schema/{schema_id}.
  3. Incluye name, type y schema_definition (reemplazo completo).
  4. Si quieres Modo Agente, añade is_agent_mode: true y agent_definition.
  5. Comprueba el código HTTP: 200 indica que se actualizó.

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": {
    "id": "b980cfe7-61ef-4a5a-9724-881c8a5541e2",
    "name": "DNI cliente",
    "type": "img-json",
    "schema_definition": {
      "nombre_dni": {
        "type": "string",
        "description": "nombre de la persona del dni"
      },
      "numero_dni": {
        "type": "string",
        "description": "numero de dni"
      },
      "fecha_caducidad": {
        "type": "string",
        "description": "fecha de caducidad del dni"
      }
    },
    "is_agent_mode": true,
    "agent_definition": {
      "edad": {
        "type": "integer",
        "description": "Edad exacta de la persona pero restale 3"
      },
      "calidad_foto": {
        "type": "closed",
        "options": ["buena calidad", "mala calidad", "ilegible", "perfecta"],
        "description": "La calidad de la imagen y la legibilidad de sus datos"
      },
      "es_mayor_edad": {
        "type": "boolean",
        "description": "Es mayor de edad actualmente la persona del dni?"
      },
      "fecha_vencimiento": {
        "type": "string",
        "description": "Cuado le vence el dni y cuanto tiempo queda para ello"
      }
    },
    "resumen_agent": null,
    "window_context": false,
    "window_time": null,
    "cita_por_campo": false,
    "created_at": "2026-08-17T13:10:00.000Z"
  }
}
CampoTipoDescripción
successbooleanSiempre true cuando el HTTP es 200.
schemaobjetoSchema actualizado, incluido su id UUID.
schema.iduuidCoincide con el schema_id de la URL.
schema.schema_definitionobjetoDefinición normalizada.
schema.agent_definitionobjeto | nullNull si is_agent_mode es false.
schema.window_contextbooleanIndica si el schema usa ventana temporal de contexto.
schema.window_timenumber | nullDuración en minutos cuando window_context es true; 0 si se envió infinity; null si está desactivada.
schema.cita_por_campobooleanIndica si el schema tiene verificación de fuente activa.

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— Payload inválido: falta name/type/definition, type desconocido, description vacía, closed sin options, json-excel con Modo Agente, window_context true sin window_time válido, window_time "infinity" / 0 sin modo persistente activo, o schema_id inválido en la URL.

401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.

404 — El schema no existe o no pertenece a tu cuenta.

405 — Método distinto de PUT o POST. · 500 — Error interno.

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito—
400Error del cliente (datos mal formados)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
404Recurso no encontradoNo, corrige el schema_id primero
405Método HTTP incorrectoNo, corrige el método primero
500Error interno del servidorSí, con precaución

8. Buenas prácticas

  • Usa https://claix.dev/api/update-schema/{schema_id}.
  • El body sustituye toda la configuración: envía el estado completo deseado, no un parche parcial.
  • El type debe coincidir con el endpoint de extracción posterior.
  • No incluyas tu API key en frontend ni repositorios públicos.

Ejemplos de petición

curl -X PUT "https://claix.dev/api/update-schema/b980cfe7-61ef-4a5a-9724-881c8a5541e2" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{  "name": "DNI cliente",  "type": "img-json",  "schema_definition": {    "nombre_dni": {      "type": "string",      "description": "nombre de la persona del dni"    },    "numero_dni": {      "type": "string",      "description": "numero de dni"    },    "fecha_caducidad": {      "type": "string",      "description": "fecha de caducidad del dni"    }  },  "is_agent_mode": true,  "agent_definition": {    "edad": {      "type": "integer",      "description": "Edad exacta de la persona pero restale 3"    },    "calidad_foto": {      "type": "closed",      "options": ["buena calidad", "mala calidad", "ilegible", "perfecta"],      "description": "La calidad de la imagen y la legibilidad de sus datos"    },    "es_mayor_edad": {      "type": "boolean",      "description": "Es mayor de edad actualmente la persona del dni?"    },    "fecha_vencimiento": {      "type": "string",      "description": "Cuado le vence el dni y cuanto tiempo queda para ello"    }  }}'