PDF → Markdown
PDF to Markdown
Endpoint
https://claix.dev/api/pdf-markdownA PDF with selectable text is converted locally. If selectable text is below the minimum (a scanned PDF), it is sent to the same model and the same BYOK path as PDF → JSON, asking only for Markdown.
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 | .pdf, 15 MB maximum. |
| 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: Only when the PDF is scanned or does not have enough selectable text.
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 file is not a PDF, 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 PDF is over 15 MB.
422 — The scanned PDF is not readable, or the resulting 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 file 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 | PDF too large | No — reduce file size first |
| 422 | No extractable data | No — review PDF/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.
- Check the PDF size in your client before sending it. A PDF with selectable text does not call the model.
- 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.