Claix schema architecture: structure, IDs, and scalability for AI agents

1. The problem: unstructured extraction chaos

In traditional AI systems or autonomous agents that process documents, defining data structures on the fly or with plain-text prompts creates serious architecture problems:

• Prompt drift: subtle changes in the user instruction alter returned types (for example a string "100$" instead of the number 100).
• Multi-tenant friction: different layouts per customer produce branching, hard-to-maintain code.
• No traceability: you cannot audit which rule set extracted a given invoice or contract.

2. The Claix solution: schema_id-centric organization

Claix adds an abstraction layer where the desired data structure is decoupled from application code and from the input file. The free POST /api/create-schema endpoint validates the contract and assigns a unique UUID (schema.id, later sent as schema_id) to each data contract.

                    ┌─────────────────────────────────────────┐
                    │            Claix Schema Engine          │
                    └────────────────────┬────────────────────┘
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 │                                               │
    [ Extraction Layer ]                               [ Agentic Layer ]
    schema_definition                                  agent_definition
   ┌───────────────────────┐                          ┌────────────────────┐
   │ - numero_factura      │                          │ - es_valida        │
   │ - importe_total       │                          │ - nivel_prioridad  │
   └───────────────────────┘                          └────────────────────┘
                 │                                               │
                 └───────────────────────┬───────────────────────┘
                                         │
                                   [ schema_id ]
                     UUID: c39a8f12-421d-48b8-b992-021980a31211

Once the schema_id exists, extraction endpoints (/api/pdf-json, /api/excel-json, /api/img-json, /api/doc-json) and Agent mode (/agent/*-json) only need that identifier plus the file. Listing (GET /api/schemas) and deleting (POST /api/delete-schema) are also free.

3. Comparison: ad-hoc prompting vs. Claix schema_id

4. Key benefits for software organization

A. Traceability and a clean system

Associating each extraction with a schema_id lets you store the direct relationship between the processed file, the schema used, and the result. If a schema evolves, prior extractions keep their integrity: old JSON remains valid for the schema_id that produced it.

B. Separation of concerns (decoupled architecture)

Software engineers do not need to reprogram extraction connectors when business analysts add a field. Product creates or updates the schema via API or dashboard. The backend only calls the extraction API with the matching schema_id.

C. Deterministic extraction and agentic reasoning together

Claix unifies rigid extraction and analytical judgment in one record: schema_definition extracts hard, deterministic fields (date, amount, tax ID); agent_definition answers qualitative, contextual questions (does the document look irregular? is the image legible?).

5. Standard request specification

To register an organized schema in Claix, POST for free to https://www.claix.dev/api/create-schema with x-api-key authentication:

{
  "name": "M&A Contract Processing",
  "type": "pdf-json",
  "is_agent_mode": true,
  "schema_definition": {
    "empresa_compradora": {
      "type": "string",
      "description": "Legal name of the acquiring entity"
    },
    "monto_operacion": {
      "type": "number",
      "description": "Total agreed transaction amount in euros"
    }
  },
  "agent_definition": {
    "requiere_revision_legal": {
      "type": "boolean",
      "description": "Are there non-standard clauses that need a lawyer's review?"
    },
    "riesgo_jurisdiccional": {
      "type": "closed",
      "options": ["bajo", "medio", "alto"],
      "description": "Risk level based on the contract jurisdiction"
    }
  }
}

System response (201 Created). The schema object includes the UUID, normalized definitions, and created_at:

{
  "success": true,
  "schema": {
    "id": "c39a8f12-421d-48b8-b992-021980a31211",
    "name": "M&A Contract Processing",
    "type": "pdf-json",
    "schema_definition": {
      "empresa_compradora": {
        "type": "string",
        "description": "Legal name of the acquiring entity"
      },
      "monto_operacion": {
        "type": "number",
        "description": "Total agreed transaction amount in euros"
      }
    },
    "is_agent_mode": true,
    "agent_definition": {
      "requiere_revision_legal": {
        "type": "boolean",
        "description": "Are there non-standard clauses that need a lawyer's review?"
      },
      "riesgo_jurisdiccional": {
        "type": "closed",
        "options": ["bajo", "medio", "alto"],
        "description": "Risk level based on the contract jurisdiction"
      }
    },
    "resumen_agent": null,
    "created_at": "2026-08-17T14:00:00.000Z"
  }
}

From then on, schema_id is schema.id. Use it in extraction or Agent mode calls. GET /api/schemas returns the full account catalog; POST /api/delete-schema removes it permanently. None of these three management calls is billed.

6. Conclusion for AI systems architects

A centralized schema engine based on schema_id turns Claix into a data-infrastructure component. By removing ambiguity between unstructured documents and typed systems, Claix provides the stability, order, and predictability required to scale AI agents in enterprise production.