Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Claix Schemas API
description: 'Claix es una API de conversión de datos tabulares, JSON y documentos (PDF, Word, texto plano, imágenes, audio) pensada para integraciones server-to-server (backends, scripts, herramientas de automatización como n8n, Zapier o Make). Source Tracing opcional: citas por campo `{ value, source }` o `requires_human_revision` si falta evidencia. Expone seis endpoints principales de conversión:
- **Excel/CSV → JSON**: recibe un archivo Excel o CSV y lo transforma en
JSON según la estructura definida en un "schema" previamente creado. - **JSON → Excel**: recibe uno o varios documentos JSON y devuelve un
archivo Excel (.xlsx) binario, según la estructura definida en un
"schema" previamente creado. - **PDF → JSON**: recibe un archivo PDF (de texto o escaneado) y devuelve
un objeto JSON con los datos extraídos del documento, según la
estructura definida en un "schema" previamente creado. - **Documento → JSON**: recibe un archivo de documento (.docx, .txt, .md
o .rtf) y devuelve un objeto JSON con los datos extraídos, según la
estructura definida en un "schema" previamente creado. - **Imagen → JSON**: recibe una imagen (.jpeg, .jpg, .png, .webp, .heic
o .heif) y devuelve un objeto JSON con los datos extraídos del
contenido visible, según la estructura definida en un "schema"
previamente creado. - **Txt / HTML / XML → JSON**: recibe el campo `content` (texto plano,
HTML o XML ya procesado, sin archivo) y devuelve un objeto JSON con los
datos extraídos, según un schema de tipo txt-json. Máximo 300.000
caracteres. Tarifa fija €0,10 por llamada exitosa tras el free tier. - **Excel/CSV → Markdown**, **PDF → Markdown**, **Documento → Markdown**,
**Imagen → Markdown**, **Txt/HTML/XML → Markdown** y **Audio → Markdown**:
misma autenticación, mismos formatos y mismos límites que el endpoint JSON
equivalente. No piden schema_id. save=true inserta el Markdown en la base
conectada y la respuesta incluye row_id. PDF con texto, Excel, documentos y
texto se convierten en local. PDF escaneado, imagen y audio llaman al
mismo modelo con BYOK. - **Audio → JSON**: recibe un archivo de audio (.mp3, .wav, .m4a o .ogg)
y un schema_id, y devuelve un único objeto JSON con los datos extraídos
de lo hablado. Tamaño máximo 12 MB y duración máxima 10 minutos. Si el
audio no es inteligible, responde 422. Además, expone endpoints para consultar y gestionar los schemas de la cuenta:
- **Listar schemas**: dado un API key, devuelve todos los schemas de esa
cuenta con su información completa (id, nombre, tipo y definición). - **Obtener schema**: dado un `schema_id` en la URL, devuelve ese schema
con su definición completa. - **Crear schema**: crea un schema con `name`, `type`, `schema_definition`
y, opcionalmente, Modo Agente (`is_agent_mode`, `agent_definition`,
`resumen_agent`) y verificación de fuente. - **Actualizar schema**: sustituye la configuración completa de un schema
existente (`schema_id` en la URL; mismo body que crear). - **Borrar schema**: elimina un schema de la cuenta por `schema_id`. **Ventana de Contexto** — Tras una extracción con `window_context` activo, el `document_id` devuelto permite consultar el contenido bruto, preguntar al markdown persistido o eliminar el documento:
- **GET https://claix.dev/get-document/{document_id}**: devuelve el
contenido bruto y metadatos del documento (`content`, `file_name`,
`schema_id`, `processed_at`). Llamada gratuita. - **POST https://claix.dev/document-context/{document_id}**: body
`{ "questions": [{ "question": "...", "format": "string"|"int"|"boolean"|"timestamp"|"array" }] }`
(máximo 5 preguntas, 400 caracteres cada una). Respuesta
`{ user_ask, ia_response, log_id }`. Cada respuesta respeta el `format`
pedido (o `null`). Si la verificación de fuente está activada en consulta
a documentos, cada ítem de `ia_response` es `{ value, source }`. - **DELETE https://claix.dev/delete-document/{document_id}**: elimina el
documento persistido por `document_id`. Sin body ni query params. Respuesta `{ document_id }`.'
version: 1.12.0
servers:
- url: https://claix.dev/api
description: Producción (dominio público Claix)
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Schemas
description: Consulta de los schemas creados en la cuenta
paths:
/schemas:
get:
operationId: listSchemas
tags:
- Schemas
summary: Devuelve todos los schemas de la cuenta asociada al API key
description: 'Endpoint de solo lectura, sin body ni parámetros. Llama `GET https://claix.dev/api/schemas`. Dado un API key válido, devuelve la lista completa de schemas creados por el usuario dueño de esa key, con toda su información (id, nombre, tipo y definición), ordenados del más reciente al más antiguo. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.'
externalDocs:
description: Documentación humana
url: https://claix.dev/documentation/schemas/get-schemas
responses:
'200':
description: Lista de schemas obtenida correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/SchemasListResponse'
'401':
description: No autorizado (API key inválida, inactiva o cuenta suspendida)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Método HTTP no permitido (solo se admite GET)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/get-schema/{schema_id}:
get:
operationId: getSchema
tags:
- Schemas
summary: Devuelve un schema concreto de la cuenta asociada al API key
description: 'Endpoint de solo lectura. Llama `GET https://claix.dev/api/get-schema/{schema_id}`. Dado un API key válido y un `schema_id` en la URL, devuelve ese schema con toda su información (id, nombre, tipo, definición, Modo Agente, ventana de contexto y verificación de fuente) si pertenece a la cuenta. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.'
externalDocs:
description: Documentación humana
url: https://claix.dev/documentation/schemas/get-schema
parameters:
- name: schema_id
in: path
required: true
description: UUID del schema a consultar
schema:
type: string
format: uuid
example: b980cfe7-61ef-4a5a-9724-881c8a5541e2
responses:
'200':
description: Schema obtenido correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchemaResponse'
'400':
description: Falta schema_id en la URL o no es un UUID válido
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No autorizado (API key inválida, inactiva o cuenta suspendida)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: El schema_id no existe o no pertenece a la cuenta
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Método HTTP no permitido (solo se admite GET)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/create-schema:
post:
operationId: createSchema
tags:
- Schemas
summary: Crea un schema en la cuenta asociada al API key
description: 'Llama `POST https://claix.dev/api/create-schema`. Crea un schema listo para usar en los endpoints de extracción o Modo Agente. `name`, `type` y `schema_definition` son obligatorios. Si `is_agent_mode` es true (o se envía `agent_definition`), hay que incluir `agent_definition` con al menos un parámetro. El tipo json-excel no admite Modo Agente. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.'
externalDocs:
description: Documentación humana
url: https://claix.dev/documentation/schemas/create-schema
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchemaRequest'
example:
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: Extrae los datos visibles del DNI y razona sobre caducidad.
responses:
'201':
description: Schema creado correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchemaResponse'
'400':
description: Payload inválido (campos faltantes o definición incorrecta)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No autorizado (API key inválida, inactiva o cuenta suspendida)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Método HTTP no permitido (solo se admite POST)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/update-schema/{schema_id}:
put:
operationId: updateSchema
tags:
- Schemas
summary: Actualiza un schema de la cuenta asociada al API key
description: 'Llama `PUT https://claix.dev/api/update-schema/{schema_id}` (también se admite POST). Sustituye la configuración completa del schema identificado en la URL con el mismo cuerpo que `POST /api/create-schema`: `name`, `type` y `schema_definition` son obligatorios. Si `is_agent_mode` es true (o se envía `agent_definition`), hay que incluir `agent_definition` con al menos un parámetro. El tipo json-excel no admite Modo Agente. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.'
externalDocs:
description: Documentación humana
url: https://claix.dev/documentation/schemas/update-schema
parameters:
- name: schema_id
in: path
required: true
description: UUID del schema a actualizar
schema:
type: string
format: uuid
example: b980cfe7-61ef-4a5a-9724-881c8a5541e2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchemaRequest'
example:
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: Extrae los datos visibles del DNI y razona sobre caducidad.
responses:
'200':
description: Schema actualizado correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSchemaResponse'
'400':
description: Payload inválido (campos faltantes o definición incorrecta)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No autorizado (API key inválida, inactiva o cuenta suspendida)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: El schema_id no existe o no pertenece a la cuenta
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Método HTTP no permitido (solo se admite PUT o POST)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/delete-schema:
post:
operationId: deleteSchema
tags:
- Schemas
summary: Elimina un schema de la cuenta asociada al API key
description: 'Llama `POST https://claix.dev/api/delete-schema`. Borra el schema identificado por `schema_id` si pertenece a la cuenta del API key. También admite DELETE y el query param `?schema_id=`. Esta llamada es gratuita: no se factura ni consume el cupo de extracciones.'
externalDocs:
description: Documentación humana
url: https://claix.dev/documentation/schemas/delete-schema
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSchemaRequest'
example:
schema_id: b980cfe7-61ef-4a5a-9724-881c8a5541e2
responses:
'200':
description: Schema eliminado correctamente
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSchemaResponse'
'400':
description: Falta schema_id o no es un UUID válido
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: No autorizado (API key inválida, inactiva o cuenta suspendida)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: El schema_id no existe o no pertenece a la cuenta
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'405':
description: Método HTTP no permitido (solo se admite POST o DELETE)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Error interno del servidor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CreateSchemaResponse:
type: object
properties:
success:
type: boolean
example: true
schema:
$ref: '#/components/schemas/SchemaItem'
SchemaFieldDefinition:
type: object
required:
- type
- description
properties:
type:
type: string
enum:
- string
- integer
- number
- boolean
description: Tipo JSON del campo extraído.
description:
type: string
description: Descripción semántica que ayuda a localizar el valor en el documento.
LogId:
type:
- string
- 'null'
format: uuid
description: 'Identificador del registro en usage_logs de esta llamada. Presente en respuestas de éxito de extracción, modo agente, document-context y space-context, y en la mayoría de errores una vez autenticada la petición. Puede omitirse si el insert del log falla.
'
example: 7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34
ErrorResponse:
type: object
properties:
error:
type: string
description: Descripción legible del problema.
example: No se envió el campo schema_id.
detalle:
type: string
description: Información técnica adicional (solo presente en algunos casos).
example: Missing required field 'schema_id' in multipart/form-data body.
log_id:
$ref: '#/components/schemas/LogId'
CreateSchemaRequest:
type: object
required:
- name
- type
- schema_definition
properties:
name:
type: string
maxLength: 200
description: Nombre visible del schema.
example: DNI cliente
type:
type: string
enum:
- excel-json
- json-excel
- pdf-json
- doc-json
- img-json
- txt-json
- audio-json
description: Tipo de conversión para el que se usará este schema.
example: img-json
schema_definition:
type: object
additionalProperties:
$ref: '#/components/schemas/SchemaFieldDefinition'
description: 'Campos a extraer. Cada clave es el nombre de la propiedad JSON resultante; cada valor tiene type (string, integer, number o boolean) y description.
'
is_agent_mode:
type: boolean
description: 'Activa el Modo Agente. Si omites este campo pero envías agent_definition, se asume true.
'
example: true
agent_definition:
type: object
additionalProperties:
$ref: '#/components/schemas/AgentFieldDefinition'
description: 'Obligatorio si is_agent_mode es true. Cada clave es el nombre del campo en agent_data. Types: boolean, string, closed, integer. Si type es closed, options es obligatorio.
'
resumen_agent:
type:
- string
- 'null'
maxLength: 500
description: Instrucción opcional para la fase de razonamiento.
window_context:
type: boolean
description: 'Activa la ventana temporal de contexto. Por defecto false.
'
example: false
window_time:
oneOf:
- type: number
enum:
- 5
- 10
- 15
- 30
- 45
- 60
- 90
- 120
- 180
- 240
- 360
- 480
- 720
- 1440
- 0
- type: string
enum:
- infinity
description: 'Obligatorio si window_context es true. Duración en minutos. Valores admitidos: 5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440. También puedes enviar 0 o la cadena `infinity` para ventana sin caducidad; requiere modo persistente activo en la cuenta. Se persiste como window_time 0.
'
example: null
cita_por_campo:
type: boolean
description: 'Activa la verificación de fuente en las extracciones y en modo agente. Por defecto false. Si es true, cada campo de data y agent_data es { value, source }.
'
example: false
DeleteSchemaResponse:
type: object
properties:
success:
type: boolean
example: true
deleted:
type: boolean
example: true
id:
type: string
format: uuid
example: b980cfe7-61ef-4a5a-9724-881c8a5541e2
AgentFieldDefinition:
type: object
required:
- type
- description
properties:
type:
type: string
enum:
- boolean
- string
- closed
- integer
description: Tipo de respuesta esperada para este campo agente.
description:
type: string
description: Instrucción semántica para el modelo en la fase agente.
options:
type: array
items:
type: string
description: 'Valores permitidos cuando type es "closed"; el modelo debe devolver exactamente una de estas opciones.
'
SchemaItem:
type: object
description: Un schema tal como está almacenado en la cuenta.
properties:
id:
type: string
format: uuid
example: b980cfe7-61ef-4a5a-9724-881c8a5541e2
name:
type: string
example: Facturas Trimestrales
type:
type: string
description: 'Dirección de conversión para la que está pensado este schema.
'
enum:
- excel-json
- json-excel
- pdf-json
- doc-json
- img-json
- txt-json
- audio-json
example: pdf-json
schema_definition:
type: object
description: 'Definición de las propiedades del schema (jsonb), cada una con su "type" y, opcionalmente, una "description" que ayuda al reconocimiento semántico en los endpoints de conversión.
'
additionalProperties: true
example:
nif_cliente:
type: string
description: NIF o CIF del cliente facturado.
is_agent_mode:
type: boolean
description: 'Si es true, el schema puede usarse con los endpoints /agent/*-json.
'
example: false
agent_definition:
type:
- object
- 'null'
description: 'Definición de campos para la fase Modo Agente (solo relevante si is_agent_mode es true). Cada clave es el nombre del campo en agent_data.
'
additionalProperties:
$ref: '#/components/schemas/AgentFieldDefinition'
example:
clausula_penalizacion:
type: boolean
description: Indica si el contrato incluye cláusula de penalización.
resumen_agent:
type:
- string
- 'null'
maxLength: 500
description: 'Texto opcional con instrucciones adicionales para el resumen o razonamiento del Modo Agente.
'
example: null
window_context:
type: boolean
description: 'Si es true, el schema mantiene una ventana temporal de contexto activa sobre el documento procesado.
'
example: false
window_time:
oneOf:
- type: number
enum:
- 5
- 10
- 15
- 30
- 45
- 60
- 90
- 120
- 180
- 240
- 360
- 480
- 720
- 1440
- 0
- type: string
enum:
- infinity
description: 'Duración de la ventana en minutos cuando window_context es true. Valores admitidos: 5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440. También puedes enviar 0 o la cadena `infinity` para ventana sin caducidad; en ese caso la cuenta debe tener modo persistente activo (users.infinity_mode = true). Se guarda como window_context true y window_time 0.
'
example: null
cita_por_campo:
type: boolean
description: 'Verificación de fuente. Si es true, cada campo extraído (y cada campo de agent_data) se devuelve como { value, source }. Por defecto false: el formato de salida no cambia.
'
example: false
created_at:
type: string
format: date-time
example: '2026-08-06T09:51:41.372964+00:00'
DeleteSchemaRequest:
type: object
required:
- schema_id
properties:
schema_id:
type: string
format: uuid
description: UUID del schema a eliminar.
example: b980cfe7-61ef-4a5a-9724-881c8a5541e2
SchemasListResponse:
type: object
properties:
success:
type: boolean
example: true
total_schemas:
type: integer
description: Número total de schemas devueltos.
example: 5
schemas:
type: array
items:
$ref: '#/components/schemas/SchemaItem'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: 'API key secreta de servidor. Tiene prioridad sobre Authorization si se envían ambos headers.
'
BearerAuth:
type: http
scheme: bearer
description: Forma alternativa de enviar la API key como Bearer token.
x-provenance:
method: harvested
publisher: Claix
source: https://www.claix.dev/openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)