Convert Files
Convert PDF, DOCX, images, audio, and more to Markdown via the POST /convert endpoint. Supports sync, async, and webhook delivery.
Convert a file to clean, structured Markdown. The endpoint supports both synchronous and asynchronous modes — async is triggered by providing a webhook_url parameter.
POST https://markdownanything.com/api/v1/convertParameters
Send the request as multipart/form-data.
Prop
Type
Supported File Types
pdf, docx, doc, xlsx, xls, pptx, ppt, html, htm, txt, rtf, csv, xml, json, md, markdown, epub, odt, ods, odp, jpg, jpeg, png, wav, mp3, m4a
Sync vs Async
When no webhook_url is provided, the API processes the file and returns the Markdown in the response body. Best for small files and real-time use cases.
Response 200
{
"success": true,
"markdown": "# My Document\n\nConverted content here...",
"credits_used": 1,
"credits_remaining": 499,
"metadata": {
"title": "My Document",
"author": "Jane Doe",
"page_count": 3
},
"token_optimization": {
"original_tokens": 1250,
"optimized_tokens": 980,
"reduction_percent": 21.6
}
}The metadata field is only included when include_metadata is true. The token_optimization field is only included when optimize_tokens is true.
When a webhook_url is provided, the API queues the conversion and returns immediately with a 202 status. The result is delivered to your webhook URL when processing completes.
Response 202
{
"id": "9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"status": "pending",
"message": "Conversion queued. Results will be sent to your webhook URL.",
"status_url": "/api/v1/conversions/9e5fcd8a-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"credits_used": 1,
"credits_remaining": 499
}Use the status_url to poll for status, or wait for the webhook delivery.
Credits are charged upfront for async conversions. If the conversion fails, credits are automatically refunded.
Credit Costs
| Conversion Type | Credit Cost |
|---|---|
| Standard | 1 credit |
| Enhanced AI (Starter) | 3 credits |
| Enhanced AI (Professional / Business) | 2 credits |
Code Examples
Sync conversion
curl -X POST https://markdownanything.com/api/v1/convert \
-H "Authorization: Bearer mda_your_token_here" \
-F "[email protected]" \
-F "include_metadata=true"Async conversion with webhook
curl -X POST https://markdownanything.com/api/v1/convert \
-H "Authorization: Bearer mda_your_token_here" \
-F "[email protected]" \
-F "webhook_url=https://example.com/webhooks/conversions" \
-F "webhook_secret=whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"With Enhanced AI and token optimization
curl -X POST https://markdownanything.com/api/v1/convert \
-H "Authorization: Bearer mda_your_token_here" \
-F "[email protected]" \
-F "use_enhanced_ai=true" \
-F "optimize_tokens=true" \
-F "include_metadata=true"Sync conversion
const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("include_metadata", "true");
const response = await fetch("https://markdownanything.com/api/v1/convert", {
method: "POST",
headers: {
Authorization: "Bearer mda_your_token_here",
},
body: form,
});
const data = await response.json();
console.log(data.markdown);Async conversion with webhook
const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append("webhook_url", "https://example.com/webhooks/conversions");
form.append("webhook_secret", "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6");
const response = await fetch("https://markdownanything.com/api/v1/convert", {
method: "POST",
headers: {
Authorization: "Bearer mda_your_token_here",
},
body: form,
});
const { id, status_url } = await response.json();
console.log(`Conversion ${id} queued. Poll: ${status_url}`);Sync conversion
import requests
url = "https://markdownanything.com/api/v1/convert"
headers = {"Authorization": "Bearer mda_your_token_here"}
with open("document.pdf", "rb") as f:
response = requests.post(
url,
headers=headers,
files={"file": f},
data={"include_metadata": "true"},
)
data = response.json()
print(data["markdown"])Async conversion with webhook
import requests
url = "https://markdownanything.com/api/v1/convert"
headers = {"Authorization": "Bearer mda_your_token_here"}
with open("document.pdf", "rb") as f:
response = requests.post(
url,
headers=headers,
files={"file": f},
data={
"webhook_url": "https://example.com/webhooks/conversions",
"webhook_secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
},
)
data = response.json()
print(f"Conversion {data['id']} queued. Poll: {data['status_url']}")Error Responses
| Status | Error Code | Description |
|---|---|---|
401 | — | Missing or invalid Bearer token |
402 | insufficient_credits | Not enough credits for this conversion |
413 | — | File exceeds server's maximum upload size |
422 | conversion_failed | The file could not be converted |
429 | — | Rate limit exceeded |
See Errors for the full error reference.