Schemas · Get
Get a schema via API
Endpoint
https://claix.dev/api/get-schema/{schema_id}Returns a single schema on the API key account, including the full definition. It is read-only: it does not process files.
The schema_id goes in the URL. Always call https://claix.dev/api/get-schema/{schema_id}.
Intended for server-to-server integrations. This call is free: it is not billed and does not consume your extraction quota.
1. Authentication
Every request must include your API key. It is a personal server credential, distinct from any session token.
Option A — Dedicated header (recommended):
x-api-key: <YOUR_API_KEY>
Option B — Standard Authorization header:
Authorization: Bearer <YOUR_API_KEY>
Either one is sufficient. If you send both, x-api-key takes priority.
The system checks that the key exists, is active, and the account is not suspended. On failure it returns 401.
2. Request format
Method: GET · Body: none · Path: schema_id (UUID)
| Parameter | Location | Required | Description |
|---|---|---|---|
| schema_id | URL | Yes | Identifier of the schema to retrieve. |
If the UUID does not exist or does not belong to your account, the response is 404 without revealing whether it exists elsewhere.
3. How to build the call
- Get the
schema_idfromGET /api/schemasor when you create the schema. - Replace
{schema_id}in the URL. - Add the authentication header.
- Check the HTTP status: only 200 means success.
4. Request examples
See the right-hand panel for cURL, JavaScript, Node.js, Python, PHP, and n8n examples.
5. Successful response
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"
}
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true when HTTP is 200. |
| schema | object | Full schema, including its UUID id. |
| schema.id | uuid | Schema identifier. |
| schema.name | string | Visible schema name. |
| schema.type | string | excel-json, json-excel, pdf-json, doc-json, img-json, txt-json, or audio-json. |
| schema.schema_definition | object | Fields to extract: each key has type and description. |
| schema.is_agent_mode | boolean | When true, the schema supports /agent/*-json endpoints. |
| schema.agent_definition | object | null | Agent mode parameters (when enabled). |
| schema.resumen_agent | string | null | Optional instruction for the agent phase. |
| schema.window_context | boolean | When true, extractions persist a queryable document_id. |
| schema.window_time | number | null | Duration in minutes when window_context is true; 0 if infinity was sent; null when disabled. |
| schema.cita_por_campo | boolean | When source verification is on, extraction and agent mode return each field as { value, source }. |
| schema.created_at | datetime | ISO 8601 creation timestamp. |
6. Error codes
{
"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 — Missing schema_id in the URL or invalid UUID.
401 — Auth failed: missing, unknown, or inactive key, or suspended account.
404 — The schema does not exist or is not yours.
405 — Method other than GET. · 500 — Internal error.
7. Status code summary
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 500 | Internal server error | Yes, with caution |
8. Best practices
- Use
https://claix.dev/api/get-schema/{schema_id}. - Prefer this endpoint when you need one schema; use
GET /api/schemasto list all. - A 404 does not distinguish “missing” from “not yours”, on purpose.
- Never put your API key in frontend code or public repos.