Schemas · Crear
Crear un schema por API
Endpoint
https://claix.dev/api/create-schemaCrea un schema en la cuenta de la API key, listo para usarse en los endpoints de extracción o Modo Agente. Equivale a crearlo desde el dashboard, con validación de tipos y definiciones.
Llama siempre a https://claix.dev/api/create-schema.
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: POST · Content-Type: application/json
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre visible del schema (máx. 200). |
| type | string | Sí | excel-json, json-excel, pdf-json, doc-json, img-json o txt-json. |
| schema_definition | objeto | Sí | Campos a extraer. Cada clave es el nombre JSON de salida. |
| is_agent_mode | boolean | No | Activa Modo Agente. Si omites el campo pero envías agent_definition, se asume true. |
| agent_definition | objeto | Si hay modo agente | Parámetros a razonar. Obligatorio si is_agent_mode es true. |
| resumen_agent | string | No | Instrucción extra para la fase agente (máx. 500). |
| window_context | boolean | No | Activa la ventana temporal de contexto. Por defecto false. |
| window_time | number | Si window_context es true | Duración de la ventana en minutos. Valores admitidos: 5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440. |
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:
{
"calidad_foto": {
"type": "closed",
"options": ["buena calidad", "mala calidad", "ilegible", "perfecta"],
"description": "La calidad de la imagen y la legibilidad de sus datos"
}
}El tipo json-excel no admite Modo Agente.
3. Cómo construir la llamada
- Ten a mano tu API key.
- Construye un POST JSON a
https://claix.dev/api/create-schema. - Incluye
name,typeyschema_definition. - Si quieres Modo Agente, añade
is_agent_mode: trueyagent_definition. - Comprueba el código HTTP: 201 indica que se creó.
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
201 Created · 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,
"created_at": "2026-08-17T13:10:00.000Z"
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 201. |
| schema | objeto | Schema persistido, incluido su id UUID. |
| schema.id | uuid | Úsalo luego como schema_id en extracción. |
| schema.schema_definition | objeto | Definición normalizada. |
| schema.agent_definition | objeto | null | Null si is_agent_mode es false. |
| schema.window_context | boolean | Indica si el schema usa ventana temporal de contexto. |
| schema.window_time | number | null | Duración en minutos cuando window_context es true; null si está desactivada. |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Payload inválido: falta name/type/definition, type desconocido, description vacía, closed sin options, json-excel con Modo Agente, o window_context true sin window_time válido.
401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.
405 — Método distinto de POST. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 201 | Creado | — |
| 400 | Error del cliente (datos mal formados) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 405 | Método HTTP incorrecto | No, corrige el método primero |
| 500 | Error interno del servidor | Sí, con precaución |
8. Buenas prácticas
- Usa
https://claix.dev/api/create-schema. - El
typedebe coincidir con el endpoint de extracción posterior. - Descriptions claras mejoran la precisión de la IA en extracción y agente.
- No incluyas tu API key en frontend ni repositorios públicos.