Claix Document Intelligence API

openapi: 3.0.3
info:
  title: Claix API
  description: >
    Claix es una API de conversión de datos tabulares, JSON y documentos
    (PDF, Word, texto plano, imágenes) pensada para integraciones server-to-server
    (backends, scripts, herramientas de automatización como n8n, Zapier o
    Make). 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.

    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).
    - **Crear schema**: crea un schema con `name`, `type`, `schema_definition`
      y, opcionalmente, Modo Agente (`is_agent_mode`, `agent_definition`,
      `resumen_agent`).
    - **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": ["..."] }` (máximo 5 preguntas, 400 caracteres cada una).
      Respuesta `{ user_ask, ia_response }`.
    - **DELETE https://claix.dev/delete-document/{document_id}**: elimina el
      documento persistido por `document_id`. Sin body ni query params.
      Respuesta `{ document_id }`. Llamada gratuita.

    **Espacios de Conocimiento** — Los documentos persistidos se pueden agrupar
    en espacios (`space_id` opcional en los endpoints de extracción). Una vez
    agrupados, se puede preguntar al espacio completo en lugar de a un único
    documento:

    - **POST https://claix.dev/create-space**: body `{ "name": "..." }`.
      Crea un espacio y devuelve `{ success, space: { space_id, name,
      created_at } }`. Llamada gratuita.
    - **DELETE https://claix.dev/delete-space/{space_id}**: elimina el espacio.
      Sin body ni query params. Respuesta `{ space_id }`. Llamada gratuita.
    - **POST https://claix.dev/space-context/{space_id}**: body
      `{ "questions": ["..."] }` (máximo 5 preguntas, 400 caracteres cada una),
      exactamente igual que document-context. La diferencia es el alcance: la
      respuesta se construye cruzando el `markdown_content` de todos los
      documentos vigentes del espacio, no de uno solo.
      Respuesta `{ user_ask, ia_response }`.

    Los seis endpoints de conversión usan reconocimiento automático de sinónimos,
    abreviaturas, traducciones y variantes de nombre entre las
    columnas/claves/campos de entrada y las propiedades definidas en el
    schema correspondiente.

    **Modo Agente** — Cinco endpoints adicionales bajo `/agent/*-json` ejecutan
    la misma extracción estructurada que sus equivalentes `/api/*-json` y, a
    continuación, una fase de razonamiento semántico según `agent_definition`
    del schema. La respuesta HTTP 200 incluye los campos habituales de
    extracción más `agent_data` (objeto tipado con booleanos, enteros, strings
    u opciones cerradas). El schema debe tener `is_agent_mode` activado.
  version: "1.8.2"
servers:
  - url: https://claix.dev/api
    description: Producción (dominio público Claix)

security:
  - ApiKeyAuth: []
  - BearerAuth: []

tags:
  - name: Excel a JSON
    description: Conversión de archivos Excel/CSV a JSON estructurado
  - name: JSON a Excel
    description: Conversión de datos JSON a archivos Excel binarios
  - name: PDF a JSON
    description: Extracción de datos estructurados a partir de archivos PDF
  - name: Documento a JSON
    description: >
      Extracción de datos estructurados a partir de documentos de texto
      (.docx, .txt, .md, .rtf)
  - name: Imagen a JSON
    description: >
      Extracción de datos estructurados a partir de imágenes
      (.jpeg, .jpg, .png, .webp, .heic, .heif)
  - name: Texto a JSON
    description: >
      Extracción de datos estructurados a partir de texto plano, HTML o XML
      ya procesado (campo content, sin archivo)
  - name: Ventana de Contexto
    description: >
      Consulta de contenido bruto, preguntas o borrado de un documento persistido
      (markdown_content) identificado por document_id. URLs públicas: GET
      https://claix.dev/get-document/{document_id}; POST
      https://claix.dev/document-context/{document_id}; DELETE
      https://claix.dev/delete-document/{document_id}.
  - name: Espacios de Conocimiento
    description: >
      Creación y borrado de espacios de conocimiento, y preguntas cruzadas
      sobre todos los documentos vigentes agrupados en uno de ellos. El formato
      de entrada y salida de las preguntas es el mismo que en la ventana de
      contexto. URLs públicas: POST https://claix.dev/create-space; DELETE
      https://claix.dev/delete-space/{space_id}; POST
      https://claix.dev/space-context/{space_id}.
  - name: Schemas
    description: Consulta de los schemas creados en la cuenta


# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/claix-dev/refs/heads/main/openapi/claix-dev-openapi.yml