API Documentation

Extraction -> Markdown

Convert files to Markdown. No schema. Optional save=true inserts the row in the connected database and returns row_id.

Image → Markdown

Image to Markdown

Endpoint

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

Transcribes the visible text of the image to Markdown. Same formats, binary signature, 15 MB limit and quality gate as Image → JSON. The model call and BYOK path are the same; the output is Markdown, not a schema.

There is no schema_id. The Markdown is always returned. Send save=true to insert that Markdown into the connected database, using the active Markdown rules. The response then includes row_id. Omit save, or send save=false, to only return the Markdown.

It is meant for server-to-server integrations (backends, scripts, n8n, Zapier, Make). Do not call it from an end-user browser: it requires a secret API key.

1. Authentication

Every request must include your API key. It is a personal server credential, separate from any session token, and it should be treated with the same care as a database password.

Option A — dedicated header (recommended):

x-api-key: <TU_API_KEY>

Option B — standard Authorization header:

Authorization: Bearer <TU_API_KEY>

Either one is enough. If you send both, x-api-key takes priority.

Before processing the file, the system checks that:

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

If that fails, the request is rejected with 401 and the file is not processed.

2. Request format

FieldTypeRequiredDescription
fileBinary fileYes.jpeg, .jpg, .png, .webp, .heic and .heif. 15 MB maximum.
saveBooleanNotrue inserts the Markdown into the connected database and returns row_id. Omit it or send false to only return the Markdown. space_id, window_time and window_context are rejected.

Method: POST · Content-Type: multipart/form-data

Model: Yes. If the image is not readable, the response is 422.

There is no schema_id. The field names must match the table exactly.

3. How to build the request

  1. Have your API key ready. You do not need a schema_id.
  2. Build a POST request to the endpoint URL.
  3. Add the authentication header.
  4. Send multipart/form-data with file.
  5. To store the row, also send save=true. Active Markdown rules are required. save=false skips the insert.
  6. Check the HTTP status: only 200 means success.

4. Request examples

See the panel on the right for cURL, JavaScript, Node.js, Python, PHP and n8n. Switch language with the selector and copy the snippet. “save=true” adds that field.

5. Successful response format

200 OK · Content-Type: application/json

Without save:

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

With save=true, the same body also includes 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"
}
FieldTypeDescription
successbooleanAlways true when HTTP is 200.
markdownstringThe converted document.
row_idstring, optionalPresent only when save is true. Id of the row inserted in the connected database.
log_idstring (UUID)Identifies the call in the logs panel. It also appears on most errors after the request is authenticated.

6. Error codes

{
  "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 — file is missing, multipart is invalid, the format or binary signature does not match, save is not true or false, or space_id, window_time or window_context is sent.

401 — Authentication failed: key missing, unknown, disabled, or the account is suspended.

409 — The row conflicts with a unique key. The body includes code unique_conflict.

413 — The image is over 15 MB.

422 — The image is not readable, or there is no text to transcribe. With save=true, this status also means the insert was refused before writing: no active Markdown rules, no connected database, or the mapped table or column does not match. The body includes error and code.

502 — The model call failed, or the insert was rejected. On an insert failure the body includes error and code, and the row is not saved.

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

7. Code summary

CodeCategoryRetry?
200Success—
400Client error (malformed image or data)No — fix the request first
401Authentication errorNo — fix credentials first
404Resource not foundNo — fix schema_id first
405Incorrect HTTP methodNo — fix the method first
413Image too largeNo — reduce file size first
422Illegible image or no extractable dataNo — review image/schema first
500Internal server errorYes, with caution
502AI service failureYes, recommended with backoff

8. Best practices

  • Check the HTTP status before reading markdown.
  • row_id is only returned when save is true. space_id, window_time and window_context are rejected.
  • Check the image size and sharpness before sending it.
  • Retry automatically only on 500 and 502, never on 4xx unless you change the request.
  • Do not put your API key in a frontend or a public repository.

Request examples

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