ClaixClaixES

API Documentation

Schema endpoints

List, get, create, update, and delete schemas in your account with the same API key used for extraction.

Schemas · Update

Update a schema via API

Endpoint

PUThttps://claix.dev/api/update-schema/{schema_id}

Replaces the full configuration of an existing schema (same body as POST /api/create-schema). The schema_id goes in the URL; the body carries name, type, schema_definition, and options.

Always call https://claix.dev/api/update-schema/{schema_id}. POST is also accepted.

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: PUT (POST also accepted) · Content-Type: application/json · Path: schema_id (UUID)

FieldTypeRequiredDescription
schema_iduuidYes (URL)Identifier of the schema to update.
namestringYesVisible schema name (max 200).
typestringYesexcel-json, json-excel, pdf-json, doc-json, img-json, txt-json, or audio-json.
schema_definitionobjectYesFields to extract. Each key is the output JSON name.
is_agent_modebooleanNoEnables Agent mode. If omitted but agent_definition is sent, true is assumed.
agent_definitionobjectIf agent modeParameters to reason over. Required when is_agent_mode is true.
resumen_agentstringNoExtra instruction for the agent phase (max 500).
window_contextbooleanNoEnables the temporal context window. Default false.
window_timenumber | stringIf window_context is trueWindow 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; stored as window_time 0.
cita_por_campobooleanNoEnables source verification: links each extracted field to its location in the original document and checks the value appears in the content. Default false.

Each field in schema_definition must look like:

{
  "nombre_dni": {
    "type": "string",
    "description": "nombre de la persona del dni"
  }
}

Allowed 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.

The json-excel type does not support Agent mode.

3. How to build the call

  1. Get the schema_id from GET /api/schemas or GET /api/get-schema/{schema_id}.
  2. Build a PUT JSON request to https://claix.dev/api/update-schema/{schema_id}.
  3. Include name, type, and schema_definition (full replacement).
  4. For Agent mode, add is_agent_mode: true and agent_definition.
  5. Check the HTTP status: 200 means it was updated.

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"
  }
}
FieldTypeDescription
successbooleanAlways true when HTTP is 200.
schemaobjectUpdated schema, including its UUID id.
schema.iduuidMatches the schema_id in the URL.
schema.schema_definitionobjectNormalized definition.
schema.agent_definitionobject | nullNull when is_agent_mode is false.
schema.window_contextbooleanWhether the schema uses a temporal context window.
schema.window_timenumber | nullDuration in minutes when window_context is true; 0 if infinity was sent; null when disabled.
schema.cita_por_campobooleanWhether 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, window_time "infinity" / 0 without Persistent Mode, or invalid schema_id in the URL.

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 PUT or POST. · 500 — Internal error.

7. Status code summary

CodeCategoryRetry?
200Success—
400Client error (malformed data)No — fix the request first
401Authentication errorNo — fix credentials first
404Resource not foundNo — fix schema_id first
405Incorrect HTTP methodNo — fix the method first
500Internal server errorYes, with caution

8. Best practices

  • Use https://claix.dev/api/update-schema/{schema_id}.
  • The body replaces the whole configuration: send the full desired state, not a partial patch.
  • type must match the extraction endpoint you will call later.
  • Never put your API key in frontend code or public repos.

Request examples

curl -X PUT "https://claix.dev/api/update-schema/b980cfe7-61ef-4a5a-9724-881c8a5541e2" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{  "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"    }  }}'