Schemas · Listar
Listar schemas de la cuenta
Endpoint
https://www.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 ni genera cargo en usage_logs.
Llama siempre a https://www.claix.dev/api/schemas. No uses la URL interna de Supabase (/functions/v1/...).
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.
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://www.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,
"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 o img-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[].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)."
}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
www.claix.dev, no la URL de Edge Functions de Supabase. - 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.