Schemas · Create
Create a schema via API
Endpoint
https://claix.dev/api/create-schemaCreates a schema on the API key account, ready for extraction or Agent mode endpoints. It matches dashboard creation, with type and definition validation.
Always call https://claix.dev/api/create-schema.
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. Failure returns 401.
2. Request format
Method: POST · Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Visible schema name (max 200). |
| type | string | Yes | excel-json, json-excel, pdf-json, doc-json, img-json, txt-json, or audio-json. |
| schema_definition | object | Yes | Fields to extract. Each key is the output JSON name. |
| is_agent_mode | boolean | No | Enables Agent mode. If omitted but agent_definition is sent, it is assumed true. |
| agent_definition | object | If agent mode | Reasoning parameters. Required when is_agent_mode is true. |
| resumen_agent | string | No | Extra instruction for the agent phase (max 500). |
| window_context | boolean | No | Enables the context time window. Defaults to false. |
| window_time | number | string | When window_context is true | Window duration in minutes (5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440) or the string "infinity" for no expiry. infinity requires Persistent Mode on the account; it is stored as window_time 0. |
| cita_por_campo | boolean | No | Enables source verification: each extracted field is bound to its location in the original document and checked against the source content. Defaults to false. |
Each schema_definition field must look like:
{
"nombre_dni": {
"type": "string",
"description": "full name printed on the ID card"
}
}Extraction types: string, integer, number, boolean. description is required.
Each agent_definition parameter uses boolean, string, closed, or integer. If type is closed, options must be a non-empty array:
{
"calidad_foto": {
"type": "closed",
"options": ["buena calidad", "mala calidad", "ilegible", "perfecta"],
"description": "Image quality and data legibility"
}
}The json-excel type does not support Agent mode.
3. How to build the call
- Have your API key ready.
- Send a JSON POST to
https://claix.dev/api/create-schema. - Include
name,type, andschema_definition. - For Agent mode, add
is_agent_mode: trueandagent_definition. - Check the HTTP status: 201 means it was created.
4. Request examples
Use the panel on the right for cURL, JavaScript, Node.js, Python, PHP, and n8n examples.
5. Successful response
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,
"cita_por_campo": false,
"created_at": "2026-08-17T13:10:00.000Z"
}
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true when HTTP is 201. |
| schema | object | Persisted schema, including its UUID. |
| schema.id | uuid | Use later as schema_id for extraction. |
| schema.schema_definition | object | Normalized definition. |
| schema.agent_definition | object | null | Null when is_agent_mode is false. |
| schema.window_context | boolean | Whether the schema uses a context time window. |
| schema.window_time | number | null | Duration in minutes when window_context is true; 0 when infinity was sent; null when disabled. |
| schema.cita_por_campo | boolean | Whether source verification is enabled on the schema. |
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— Invalid payload: missing name/type/definition, unknown type, empty description, closed without options, json-excel with Agent mode, window_context true without a valid window_time, or window_time "infinity" / 0 without Persistent Mode enabled.
401 — Authentication failed: missing, unknown, or disabled key, or suspended account.
405 — Method other than POST. · 500 — Internal error.
7. Status code summary
| Code | Category | Retry? |
|---|---|---|
| 201 | Created | — |
| 400 | Client error (malformed data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials 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/create-schema. typemust match the extraction endpoint you will call later.- Clear descriptions improve AI accuracy for extraction and agent reasoning.
- Never put your API key in frontend code or public repos.