Documentación API

Extracción -> Markdown

Convierte archivos a Markdown. Sin schema. save=true opcional inserta la fila en la base conectada y devuelve row_id.

PDF → Markdown

PDF a Markdown

Endpoint

POSThttps://claix.dev/api/pdf-markdown

Un PDF con texto seleccionable se convierte en local. Si el texto seleccionable no llega al mínimo (PDF escaneado), se envía al mismo modelo y al mismo BYOK que PDF → JSON, pidiendo solo Markdown.

No hay schema_id. El Markdown siempre se devuelve. Con save=true se inserta en la base conectada, según las reglas activas de Markdown, y la respuesta incluye row_id. Si omites save, o envías save=false, solo se devuelve el Markdown.

Está pensado para integraciones server-to-server (backends, scripts, n8n, Zapier, Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión, y debe tratarse con el mismo cuidado que una contraseña de base de datos.

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.

Antes de procesar el archivo, el sistema valida que:

  • La API key exista y esté activa.
  • La cuenta asociada esté activa (no suspendida).

Si falla, se rechaza con 401 sin procesar el archivo.

2. Formato de la petición

CampoTipoObligatorioDescripción
fileArchivo binarioSí.pdf, máximo 15 MB.
saveBooleanoNotrue inserta el Markdown en la base conectada y devuelve row_id. Si no viene, o es false, solo se devuelve el Markdown. space_id, window_time y window_context se rechazan.

Método: POST · Content-Type: multipart/form-data

Modelo: Solo si el PDF es escaneado o no tiene texto seleccionable suficiente.

No hay schema_id. Los nombres de campo tienen que coincidir exactamente con la tabla.

3. Cómo construir la llamada

  1. Ten a mano tu API key. No necesitas schema_id.
  2. Construye un POST a la URL del endpoint.
  3. Añade el header de autenticación.
  4. Envía multipart/form-data con file.
  5. Para guardar la fila, envía también save=true. Hacen falta reglas activas de Markdown. save=false no inserta.
  6. Comprueba el código HTTP: solo 200 indica éxito.

4. Ejemplos de llamada

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n. Puedes cambiar el lenguaje con el selector y copiar el código. «save=true» añade ese campo.

5. Formato de la respuesta exitosa

200 OK · Content-Type: application/json

Sin save:

{
  "success": true,
  "markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Con save=true, el mismo cuerpo incluye además row_id:

{
  "success": true,
  "markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
  "row_id": "9b1e4c80-2a7d-4e11-8f33-0c6d5a4b2e18",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}
CampoTipoDescripción
successbooleanSiempre true cuando el HTTP es 200.
markdownstringEl documento convertido.
row_idstring, opcionalSolo aparece si save es true. Id de la fila insertada en la base conectada.
log_idstring (UUID)Identifica la llamada en el panel de logs. También aparece en la mayoría de errores una vez autenticada la petición.

6. Códigos de error

{
  "error": "Descripción legible del problema.",
  "code": "no_rules",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

400 — Falta file, el multipart es incorrecto, el archivo no es un PDF, save no es true ni false, o llegan space_id, window_time o window_context.

401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.

409 — La fila choca con una clave única. El cuerpo incluye code unique_conflict.

413 — El PDF supera 15 MB.

422 — El PDF escaneado no es legible, o el Markdown resultante está vacío. Con save=true, este estado también indica que el insert se rechazó antes de escribir: no hay reglas activas de Markdown, no hay base conectada, o la tabla o columna de la regla no coincide. El cuerpo incluye error y code.

502 — Fallo del servicio de IA, o el insert fue rechazado. Si falla el insert, el cuerpo incluye error y code, y la fila no se guarda.

405 — Método distinto de POST. · 500 — Error interno.

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito—
400Error del cliente (archivo o datos mal formados)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
404Recurso no encontradoNo, corrige el schema_id primero
405Método HTTP incorrectoNo, corrige el método primero
413PDF demasiado grandeNo, reduce el tamaño del archivo primero
422Sin datos extraíblesNo, revisa el PDF/schema primero
500Error interno del servidorSí, con precaución
502Fallo del servicio de IASí, recomendado con backoff

8. Buenas prácticas

  • Valida el código HTTP antes de leer markdown.
  • row_id solo se devuelve si save es true. space_id, window_time y window_context se rechazan.
  • Comprueba el tamaño del PDF en tu cliente antes de enviarlo. Un PDF con texto seleccionable no llama al modelo.
  • Reintenta automáticamente solo en 500 y 502, nunca en 4xx salvo cambios en la petición.
  • No incluyas tu API key en frontend ni repositorios públicos.

Ejemplos de petición

curl -X POST "https://claix.dev/api/pdf-markdown" \
  -H "x-api-key: <TU_API_KEY>" \
  -F "file=@./contrato.pdf"