Claix Markdown API

openapi: 3.2.0
info:
  title: Claix Markdown 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: Markdown
  description: Conversión de archivos a Markdown, sin schema. Mismos formatos que los endpoints de extracción a JSON. space_id es opcional. PDF digital, Excel, documentos de texto y txt/HTML/XML se convierten en local. PDF escaneado, imagen y audio usan el mismo modelo y el mismo BYOK que su endpoint JSON.
paths:
  /excel-markdown:
    post:
      operationId: excelToMarkdown
      tags:
      - Markdown
      summary: Convierte la primera hoja de un Excel o CSV a Markdown
      description: Igual que /excel-json en autenticación, formatos y parseo de la primera hoja, sin schema_id y sin llamada a un modelo. Devuelve el Markdown. El Markdown se devuelve siempre. Con save=true se inserta en la base conectada, según las reglas activas de Markdown, y la respuesta incluye row_id. save=false, o omitir save, no inserta.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownFileRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: Archivo ausente, vacío o ilegible, o save distinto de true o false
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: La fila choca con una clave única de la base conectada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Archivo demasiado grande
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: No se pudo producir Markdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /pdf-markdown:
    post:
      operationId: pdfToMarkdown
      tags:
      - Markdown
      summary: Convierte un PDF a Markdown
      description: PDF con texto seleccionable se convierte en local. Un PDF escaneado usa el mismo modelo y el mismo BYOK que /pdf-json, pidiendo solo Markdown. Máximo 15 MB. Sin schema_id.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownFileRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: Archivo ausente o que no es un PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: PDF por encima de 15 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: PDF escaneado ilegible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Fallo de la llamada al modelo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /doc-markdown:
    post:
      operationId: docToMarkdown
      tags:
      - Markdown
      summary: Convierte un documento de texto a Markdown
      description: Acepta .docx, .txt, .md y .rtf, máximo 10 MB, igual que /doc-json. El .doc antiguo se rechaza. Conversión local, sin schema_id y sin modelo.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownFileRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: Formato no soportado, archivo vacío o .doc legacy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Documento por encima de 10 MB o 300000 caracteres
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /img-markdown:
    post:
      operationId: imgToMarkdown
      tags:
      - Markdown
      summary: Transcribe una imagen a Markdown
      description: Mismos formatos (.jpeg, .jpg, .png, .webp, .heic, .heif), firma binaria, máximo 15 MB y control de calidad que /img-json. La llamada al modelo y BYOK es la misma. Sin schema_id. 422 si la imagen no es legible.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownFileRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: Formato no soportado o firma binaria inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Imagen por encima de 15 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Imagen ilegible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Fallo de la llamada al modelo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /txt-markdown:
    post:
      operationId: txtToMarkdown
      tags:
      - Markdown
      summary: Convierte texto, HTML o XML a Markdown
      description: Campo content, sin archivo, máximo 300000 caracteres, igual que /txt-json. Conversión local, sin schema_id y sin modelo.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownContentRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: content ausente o vacío
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Más de 300000 caracteres
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /audio-markdown:
    post:
      operationId: audioToMarkdown
      tags:
      - Markdown
      summary: Transcribe un audio a Markdown
      description: Mismos formatos (.mp3, .wav, .m4a, .ogg), firma binaria, máximo 12 MB y 10 minutos que /audio-json. La llamada al modelo y BYOK es la misma. Sin schema_id. 422 si no hay habla inteligible.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkdownFileRequest'
      responses:
        '200':
          description: Markdown generado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkdownSuccessResponse'
        '400':
          description: Formato no soportado o firma binaria inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API key inválida o cuenta no activa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Audio por encima de 12 MB o 10 minutos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Audio sin habla inteligible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Fallo de la llamada al modelo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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
    MarkdownContentRequest:
      type: object
      required:
      - content
      properties:
        content:
          type: string
          description: Texto plano, HTML o XML. Máximo 300000 caracteres.
        save:
          type: boolean
          description: Igual que en MarkdownFileRequest.
    MarkdownSuccessResponse:
      type: object
      required:
      - success
      - markdown
      properties:
        success:
          type: boolean
          example: true
        markdown:
          type: string
          description: Documento convertido a Markdown.
        total_filas_procesadas:
          type: integer
          description: Solo en Excel/CSV → Markdown. Filas de la primera hoja.
        row_id:
          type: string
          description: 'Presente solo si save era true. Id de la fila insertada en la base conectada.

            '
        log_id:
          type: string
          format: uuid
    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'
    MarkdownFileRequest:
      type: object
      required:
      - file
      properties:
        file:
          type: string
          format: binary
          description: Archivo a convertir. Los formatos admitidos dependen del endpoint.
        save:
          type: boolean
          description: 'Si es true, el Markdown se inserta en la base conectada según las reglas activas de Markdown y la respuesta incluye row_id. Si no viene, o es false, solo se devuelve el Markdown. space_id, window_time y window_context se rechazan.

            '
  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)