Why Use a Document Conversion API?
Manual document conversion doesn't scale. Whether you're building a RAG pipeline, automating content migration, or processing document uploads in your app, you need programmatic access to reliable document conversion.
Building your own parser is tempting — until you deal with the edge cases. PDF table extraction alone has consumed entire engineering teams. The MDConvert API gives you production-ready conversion: upload a file, get clean Markdown back.
RAG Pipelines
Convert documents to Markdown for vector embedding and retrieval
CMS Migration
Programmatically migrate thousands of documents between platforms
Document Processing
Handle user uploads in your SaaS app — extract text and structure
Data Extraction
Pull structured data from PDFs, spreadsheets, and presentations
API Overview & Authentication
The MDConvert API is a REST API that accepts file uploads and returns structured Markdown. Authentication uses API keys passed in the request headers.
Getting Your API Key
- 1.Sign up or log in at app.markdownconverters.com
- 2.Subscribe to Starter ($8.99/month) or higher for API access
- 3.Go to Dashboard → API Keys → Create New Key
- 4.Copy your key and store it securely (it's shown only once)
Rate Limits by Plan
| Plan | Conversions/month | Max File Size | AI Vision |
|---|---|---|---|
| Starter ($8.99) | 500 | 100MB | 50 credits |
| Pro ($29.99) | 5,000 | 1GB | 500 credits |
| Scale ($99.99) | 25,000 | 2GB | 2,000 credits |
Quick Start: Convert Your First PDF
The simplest way to test the API is with cURL. Replace YOUR_API_KEY with your actual key:
curl -X POST https://api.markdownconverters.com/convert \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-F "file=@document.pdf" \
-F 'options={"aiVision": false}'The response is JSON with the converted Markdown:
{
"success": true,
"markdown": "# Document Title\n\nConverted content here...",
"metadata": {
"fileName": "document.pdf",
"pageCount": 12,
"fileSize": 245000,
"conversionTime": 1.42
}
}Python Integration
Here's a complete Python example using the requests library. This handles single file conversion, error handling, and saving the output.
import requests
import json
from pathlib import Path
API_KEY = "your_api_key_here"
API_URL = "https://api.markdownconverters.com/convert"
def convert_file(file_path: str, ai_vision: bool = False) -> str:
"""Convert a single file to Markdown."""
headers = {"Authorization": f"Bearer {API_KEY}"}
options = json.dumps({"aiVision": ai_vision})
with open(file_path, "rb") as f:
response = requests.post(
API_URL,
headers=headers,
files={"file": (Path(file_path).name, f)},
data={"options": options},
timeout=120,
)
response.raise_for_status()
result = response.json()
if not result.get("success"):
raise Exception(f"Conversion failed: {result.get('error')}")
return result["markdown"]
# Convert a single file
markdown = convert_file("research_paper.pdf")
Path("output.md").write_text(markdown)
print("Converted successfully!")
# Batch convert a directory
def batch_convert(directory: str, output_dir: str = "output"):
"""Convert all supported files in a directory."""
input_path = Path(directory)
out_path = Path(output_dir)
out_path.mkdir(exist_ok=True)
supported = {".pdf", ".docx", ".doc", ".xlsx", ".pptx",
".html", ".epub", ".csv", ".json", ".xml"}
for file in input_path.iterdir():
if file.suffix.lower() in supported:
try:
md = convert_file(str(file))
out_file = out_path / f"{file.stem}.md"
out_file.write_text(md)
print(f"✓ {file.name}")
except Exception as e:
print(f"✗ {file.name}: {e}")
batch_convert("./documents")Node.js / TypeScript Integration
Here's the equivalent in TypeScript using the built-in fetch API (Node 18+):
import { readFile, writeFile, readdir } from "fs/promises";
import { join, extname, basename } from "path";
const API_KEY = "your_api_key_here";
const API_URL = "https://api.markdownconverters.com/convert";
async function convertFile(
filePath: string,
aiVision = false
): Promise<string> {
const fileBuffer = await readFile(filePath);
const fileName = basename(filePath);
const formData = new FormData();
formData.append("file", new Blob([fileBuffer]), fileName);
formData.append("options", JSON.stringify({ aiVision }));
const response = await fetch(API_URL, {
method: "POST",
headers: { Authorization: `Bearer ${API_KEY}` },
body: formData,
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const result = await response.json();
if (!result.success) throw new Error(result.error);
return result.markdown;
}
// Convert a single file
const markdown = await convertFile("contract.pdf");
await writeFile("contract.md", markdown);
// Batch convert with concurrency limit
async function batchConvert(dir: string, concurrency = 5) {
const files = await readdir(dir);
const supported = new Set([
".pdf", ".docx", ".xlsx", ".pptx", ".html", ".epub",
]);
const toConvert = files.filter((f) =>
supported.has(extname(f).toLowerCase())
);
for (let i = 0; i < toConvert.length; i += concurrency) {
const batch = toConvert.slice(i, i + concurrency);
await Promise.all(
batch.map(async (file) => {
try {
const md = await convertFile(join(dir, file));
const outName = file.replace(extname(file), ".md");
await writeFile(join("output", outName), md);
console.log(`✓ ${file}`);
} catch (e) {
console.error(`✗ ${file}: ${e}`);
}
})
);
}
}
await batchConvert("./documents");AI Vision via API
For scanned PDFs, images with text, or documents with complex layouts, enable AI Vision by setting aiVision: true in the options:
# Enable AI Vision for a scanned document
curl -X POST https://api.markdownconverters.com/convert \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@scanned_contract.pdf" \
-F 'options={"aiVision": true}'When to Use AI Vision
AI Vision uses credits: 1 credit per 5 pages for documents, 1 credit per image. Check your credit balance via the dashboard.
Best Practices
Use retries with exponential backoff
Network errors and rate limits happen. Retry failed requests with increasing delays (1s, 2s, 4s).
Check file types before upload
Validate the file extension before sending to the API. Unsupported types return errors and waste API calls.
Cache conversion results
If you convert the same file multiple times, cache the Markdown output. Use a content hash as the cache key.
Limit batch concurrency
Don't fire 500 requests simultaneously. Use a concurrency limit of 5-10 to avoid rate limiting.
Secure your API key
Never commit API keys to source control. Use environment variables or a secrets manager.
Get Started with the API
API access starts at $8.99/month with the Starter plan (500 conversions/month). For high-volume pipelines, Scale gives you 25,000 conversions and 2,000 AI Vision credits.