Document → Markdown
Document to Markdown
Endpoint
https://claix.dev/api/doc-markdownConverts .docx, .txt, .md and .rtf to Markdown locally. Legacy .doc is rejected, the same as Document → JSON. There is no schema and no model call.
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
| Field | Type | Required | Description |
|---|---|---|---|
| file | Binary file | Yes | .docx, .txt, .md and .rtf. Maximum 10 MB and 300,000 extracted characters. .doc is not supported. |
| save | Boolean | No | true 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: No.
There is no schema_id. The field names must match the table exactly.
3. How to build the request
- Have your API key ready. You do not need a schema_id.
- Build a POST request to the endpoint URL.
- Add the authentication header.
- Send
multipart/form-datawithfile. - To store the row, also send
save=true. Active Markdown rules are required.save=falseskips the insert. - 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"
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true when HTTP is 200. |
| markdown | string | The converted document. |
| row_id | string, optional | Present only when save is true. Id of the row inserted in the connected database. |
| log_id | string (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 is not supported (including .doc), the file is empty, 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 file is over 10 MB or the extracted text is over 300,000 characters.
422 — The document has no extractable text, or the Markdown is empty. 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
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed document or data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 413 | File or extracted text too large | No — reduce size first |
| 422 | No extractable data | No — review document/schema first |
| 500 | Internal server error | Yes, with caution |
| 502 | AI service failure | Yes, 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.
- Do not send legacy .doc: convert it to .docx first.
- 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.