Claix is an AI document intelligence API that converts unstructured files into schema-based JSON and queryable document context for developers, backends, automations, and AI agents. It processes PDFs, Excel spreadsheets, Word documents, images, text, HTML, XML, and audio using multimodal models, so you can extract structured data and query documents on demand. Integrate via REST, native Agent-to-Agent (A2A) (POST /a2a, Agent Card at /.well-known/agent.json), or MCP from IDEs and tool frameworks.

Is Claix A2A? Does Claix support Agent-to-Agent?

Yes. Claix implements the Agent-to-Agent (A2A) protocol as a first-class integration surface. Peer agents discover Claix via the Agent Card at https://www.claix.dev/.well-known/agent.json, POST JSON-RPC to /a2a, invoke 20+ document skills mapped from OpenAPI, and receive structured Task responses with DataPart payloads. A2A is ideal when one autonomous agent must delegate PDF/Excel extraction, document memory, or cross-document queries to a specialized document-intelligence agent without IDE setup. REST and MCP remain available—choose A2A for agent-to-agent orchestration.

What is the Claix MCP server?

Claix exposes a Model Context Protocol (MCP) server at /mcp so IDEs (Cursor, Claude Desktop, Windsurf) and MCP clients can invoke extraction, Agent Mode, context window, and knowledge-space tools in one click. Use MCP when a developer or copilot needs interactive document tools inside an IDE; use A2A when another autonomous agent must call Claix programmatically over the Agent-to-Agent protocol.

Which file formats can I convert to structured JSON?

Claix natively supports PDF (.pdf), Excel workbooks (.xlsx, .xls), Word documents (.docx, .doc), images (.png, .jpg, .jpeg, .webp), and plain text files (.txt, .html, .md). Each format is processed with visual document understanding to return typed, validated JSON conforming to your custom schema.

How do I convert Excel spreadsheets to JSON with the API?

To convert an Excel file, send a POST request to /api/excel-json with your file and target JSON schema. Claix interprets multi-sheet workbooks, merged headers, and relational tables, returning clean JSON ready for ingestion.

Can I convert PDFs, Word documents, and images to JSON?

Yes. Claix provides dedicated endpoints for each format: /api/pdf-json for complex or scanned PDFs, /api/doc-json for Word files, /api/img-json for images and receipts, and /api/audio-json for spoken audio (MP3, WAV, M4A, OGG). Every endpoint outputs valid JSON according to your schema.

Who is Claix built for?

Claix is designed for software developers, AI agent builders, SaaS engineering teams, and automation specialists using platforms like n8n or Make. It eliminates the need to build custom OCR, chunking, and vector retrieval pipelines.

What is the Claix pricing model?

Claix offers two native modes. With Claix Managed AI you pay per successful document (from €0.10 for images to €0.20 for audio) plus €0.03 per follow-up question, with 100 free successful processing runs on new accounts and no mandatory monthly subscription for standard extraction. With Bring Your Own Key (BYOK) there is no additional Claix document-processing fee: you connect your own OpenAI, Gemini, Claude, or Grok key and pay only that provider’s token usage while Claix still handles schemas, structured JSON, document context, and automation-ready responses.

Is document processing free with Bring Your Own Key (BYOK)?

Yes. BYOK is a native Claix option: connect your own supported AI provider API key, choose a compatible model, and process PDFs, Excel, Word, images, and text through Claix with no additional Claix processing fee. You remain responsible for your provider’s token charges. Your Claix API key still authenticates the workspace. Managed AI remains available when you prefer Claix-managed rates and defaults.

What is Source Tracing in Claix?

Source Tracing is optional field-level citation: each extracted value can include a source anchored to the document. When that check fails, source is requires_human_revision so a person can review the field. It reduces AI hallucination risk; it does not claim to eliminate it.

Are failed requests charged to my account?

No. Claix only charges for successful HTTP 200 processing requests that return valid extracted data. Failed API calls due to invalid parameters or system errors do not consume your quota or balance.

What is Claix Agent Mode?

Claix Agent Mode (/agent/*-json) is an extraction mode where an AI agent interprets ambiguous documents using natural language instructions instead of a rigid schema, allowing dynamic extraction based on context.

What is the difference between normal extraction and Agent Mode?

Normal extraction enforces strict, deterministic schema conformance for predictable pipelines. Agent Mode allows natural language reasoning over document contents, ideal for unstructured contracts and variable layouts.

How do I ask follow-up questions to a single document?

When you process a document with context enabled, Claix returns a document_id. You can send questions to POST /document-context/{document_id} to query that specific file without re-uploading or reprocessing.

What is the temporary context window?

The context window is a temporary retention layer that keeps a processed document queryable for follow-up questions without permanent storage, enabling multi-turn agent interactions before expiring automatically.

What are Knowledge Spaces, and how do I query multiple documents at once?

Knowledge Spaces allow you to group multiple persistent documents under a single space_id. By sending questions to POST /space-context/{space_id}, your backend, automation, or AI agent can query, compare, calculate totals, and cross-reference data across all active documents in that space simultaneously.

Can I white-label Claix or integrate it into automated workflows?

Yes. Claix is fully headless and integrates server-to-server via API keys, making it compatible with custom SaaS backends and automation platforms like n8n or Make.

PDF-to-JSON · Agent mode

PDF to JSON with Agent mode

Endpoint

POSThttps://claix.dev/agent/pdf-json

Agent mode active

This endpoint runs structured extraction from the main schema first, then a reasoning phase with agent_definition. The response includes data[] (extraction), agent_data (typed inference), and log_id. The schema must have is_agent_mode enabled.

This endpoint accepts a PDF file and returns a single JSON object with the data extracted from the document, following exactly the structure you define via a schema. It works with selectable-text PDFs and scanned PDFs, because analysis is performed by an AI model with native document understanding, not a plain-text extractor.

It is intended for server-to-serverintegrations (backends, scripts, n8n/Zapier/Make). It must not be called from an end user's browser because it requires a secret API key.

Unlike Excel/CSV, the full PDF is treated as a single data source and the response contains exactly one record in data — ideal for invoices, contracts, forms, certificates, or reports.

1. Authentication

Every request must include your API key. It is a personal server credential and should be handled with the same care as a database password.

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.

Before processing the PDF, the system validates that:

The API key exists and is active.
The associated account is active (not suspended).

If validation fails, the request is rejected with 401 without processing the file.

2. Request format

Method: POST · Content-Type: multipart/form-data (required)

Field	Type	Required	Description
file	Binary file	Yes	The PDF to analyze. Must be the file itself, not a path or URL.
schema_id	Text (UUID)	Yes	Schema previously created in your account, of type PDF → JSON.
space_id	Text (UUID)	No	Optional. Knowledge space the stored document is attached to. Must belong to the same account as the API key. It only takes effect when the schema has the context window enabled, which is when the document is stored. You can then query the whole space with POST /space-context/{space_id}.

Field names must be exactly file and schema_id. Aliases such as pdf, documento, or upload are not supported.

The schema_id must correspond to a schema of type PDF → JSON. If you send one of Excel → JSON or another type, you will receive 400.

File requirements:

Format: .pdf only (validated by MIME type and extension).
Cannot be empty (0 bytes).
Maximum size: 15 MB (413 error if exceeded).
Compatible with text and scanned PDFs.

3. How to build the request

Have your API key and the correct schema_id ready.
Build a POST request to the endpoint URL.
Add the authentication header.
Send multipart/form-data with file (PDF) and schema_id.
Check the HTTP status code: only 200 indicates success.

4. Request examples

See the panel on the right for examples in cURL, JavaScript, Node.js, Python, PHP, and n8n.

5. Successful response format

200 OK · Content-Type: application/json

{
  "success": true,
  "schema_utilizado": "Contratos",
  "total_registros": 1,
  "data": [
    {
      "puesto a ocupar": "Ing. Software Principal (Backend)",
      "Nombre contratante": "Tech Solutions S.L.",
      "fecha del contrato": "8 de Agosto de 2026",
      "persona contratada": "Gael Anaya"
    }
  ],
  "agent_data": {
    "salario": 55000,
    "es_parcial": false,
    "fecha_contrato": "después del 20/07/2026",
    "resumen_contrato": "Contrato indefinido: Gael Anaya como Backend en Tech Solutions S.L. Jornada completa, 55.000 €/año."
  },
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Field	Type	Description
success	boolean	Always true when HTTP is 200.
schema_utilizado	string	Name of the schema used for extraction.
total_registros	number	Number of records in data.
data	array	Objects extracted from the main schema (same as extraction mode). If source verification is enabled on the schema, each property is { value, source }.
agent_data	object	Typed Agent Mode answers per agent_definition (booleans, numbers, strings). If source verification is enabled on the schema, each field is { value, source }.
log_id	string (UUID)	UUID of this call’s usage_logs row. Present on success and on most authenticated errors.

Every response includes log_id (the UUID of the usage_logs row) when the log could be stored. It also appears on most errors after the request is authenticated. Use it to find the call in the logs panel.

If source verification is enabled on the schema, each extracted property (and each agent_data field in Agent mode) becomes { "value": ..., "source": "..." } instead of a bare value. source is required: it cites the evidence (page, paragraph, cell, quoted snippet, image region, or the second / second range in audio). If there is no evidence, source is exactly requires_human_revision. If source verification is off, the format is unchanged.

Example with source verification enabled:

{
  "success": true,
  "schema_utilizado": "Contratos",
  "total_registros": 1,
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34",
  "data": [
    {
      "persona contratada": {
        "value": "Gael Anaya",
        "source": "página 1, párrafo 1"
      }
    }
  ],
  "agent_data": {
    "salario": {
      "value": 55000,
      "source": "página 2, cláusula retributiva"
    },
    "es_parcial": {
      "value": false,
      "source": "requires_human_revision"
    }
  }
}

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 file or schema_id, invalid multipart, not a PDF, empty file, corrupt file, or schema of the wrong type.

401 — Authentication failed.

404 — schema_id does not exist or does not belong to your account.

413 — PDF exceeds 15 MB.

422 — PDF read but no extractable data according to the schema.

502 — AI service failure (transient).

405 — Method other than POST. · 500 — Internal error.

7. Code summary

Code	Category	Retry?
200	Success	—
400	Client error (malformed file or 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
413	PDF too large	No — reduce file size first
422	No extractable data	No — review PDF/schema first
500	Internal server error	Yes, with caution
502	AI service failure	Yes, recommended with backoff

8. Best practices

Validate the HTTP status code before reading data[0].
Check the PDF size on your client before sending it.
Remember: data always has exactly one element (one document = one object).
Retry automatically only on 500 and 502, never on 400, 401, 404, 413, or 422.
Clear descriptions on schema properties improve accuracy on documents with non-standard layouts.
Do not include your API key in frontend code or public repositories.