Schemas · Obtener
Obtener un schema por API
Endpoint
https://claix.dev/api/get-schema/{schema_id}Devuelve un único schema de la cuenta asociada a la API key, con su definición completa. Es de solo lectura: no procesa archivos.
El schema_id viaja en la URL. Llama siempre a https://claix.dev/api/get-schema/{schema_id}.
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: GET · Body: ninguno · Path: schema_id (UUID)
| Parámetro | Ubicación | Obligatorio | Descripción |
|---|---|---|---|
| schema_id | URL | Sí | Identificador del schema a consultar. |
Si el UUID no existe o no pertenece a tu cuenta, responde 404 sin revelar si existe en otra cuenta.
3. Cómo construir la llamada
- Obtén el
schema_idconGET /api/schemaso al crear el schema. - Sustituye
{schema_id}en la URL. - Añade el header de autenticación.
- Comprueba el código HTTP: solo 200 indica éxito.
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"
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema | objeto | Schema completo, incluido su id UUID. |
| schema.id | uuid | Identificador del schema. |
| schema.name | string | Nombre visible del schema. |
| schema.type | string | excel-json, json-excel, pdf-json, doc-json, img-json, txt-json o audio-json. |
| schema.schema_definition | objeto | Campos a extraer: cada clave tiene type y description. |
| schema.is_agent_mode | boolean | Si es true, el schema admite endpoints /agent/*-json. |
| schema.agent_definition | objeto | null | Parámetros del Modo Agente (si está activo). |
| schema.resumen_agent | string | null | Instrucción opcional para la fase agente. |
| schema.window_context | boolean | Si es true, las extracciones persisten un document_id consultable. |
| schema.window_time | number | null | Duración en minutos cuando window_context es true; 0 si se envió infinity; null si está desactivada. |
| schema.cita_por_campo | boolean | Si la verificación de fuente está activa, extracción y modo agente devuelven cada campo como { value, source }. |
| schema.created_at | datetime | Fecha de creación ISO 8601. |
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 schema_id en la URL o no es un UUID válido.
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 GET. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (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 |
| 500 | Error interno del servidor | Sí, con precaución |
8. Buenas prácticas
- Usa
https://claix.dev/api/get-schema/{schema_id}. - Prefiere este endpoint cuando solo necesitas un schema; usa
GET /api/schemaspara listar todos. - Un 404 no distingue “no existe” de “no es tuyo”, a propósito.
- No incluyas tu API key en frontend ni repositorios públicos.