Schemas · Listar
Listar schemas de la cuenta
Endpoint
https://claix.dev/api/schemasEste endpoint devuelve todos los schemas asociados a la API key, con su definición completa. Es de solo lectura: no procesa archivos.
Llama siempre a https://claix.dev/api/schemas.
Está pensado para integraciones server-to-server (backends, scripts, n8n/Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.
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.
Antes de devolver datos, el sistema valida que:
- La API key exista y esté activa.
- La cuenta asociada esté activa (no suspendida).
Si falla, se rechaza con 401.
2. Formato de la petición
Método: GET · Body: ninguno · Query params: ninguno
No envíes schema_id ni filtros: la respuesta incluye todos los schemas de la cuenta, del más reciente al más antiguo.
3. Cómo construir la llamada
- Ten a mano tu API key de servidor.
- Construye un GET a
https://claix.dev/api/schemas. - 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,
"total_schemas": 2,
"schemas": [
{
"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"
}
},
"is_agent_mode": true,
"agent_definition": {
"es_mayor_edad": {
"type": "boolean",
"description": "Es mayor de edad actualmente la persona del dni?"
}
},
"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. |
| total_schemas | number | Número de schemas devueltos. |
| schemas | array | Lista de schemas de la cuenta. |
| schemas[].id | uuid | Identificador del schema. |
| schemas[].name | string | Nombre visible del schema. |
| schemas[].type | string | excel-json, json-excel, pdf-json, doc-json, img-json, txt-json o audio-json. |
| schemas[].schema_definition | objeto | Campos a extraer: cada clave tiene type y description. |
| schemas[].is_agent_mode | boolean | Si es true, el schema admite endpoints /agent/*-json. |
| schemas[].agent_definition | objeto | null | Parámetros del Modo Agente (si está activo). |
| schemas[].resumen_agent | string | null | Instrucción opcional para la fase agente. |
| schemas[].window_context | boolean | Si es true, las extracciones persisten un document_id consultable. |
| schemas[].cita_por_campo | boolean | Si la verificación de fuente está activa, extracción y modo agente devuelven cada campo como { value, source }. |
| schemas[].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"
}401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.
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 |
| 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 siempre el dominio público
claix.dev. - Guarda el
idde cada schema para las llamadas de extracción o para/api/delete-schema. - Este GET no se factura; puedes usarlo para sincronizar catálogos.
- No incluyas tu API key en frontend ni repositorios públicos.