All examples require Python with the requests library and a valid API key. Install with: pip install requests
Replace your_api_key_here with your actual API key.
Convert a single file using direct file upload (recommended) or Base64 encoding. Markdown content is automatically included in responses.
import requests
url = "https://api.markdownconverters.com/api/v1/convert"
headers = {"X-API-Key": "your_api_key_here"}
with open("/path/to/your/document.pdf", "rb") as file:
files = {"file": file}
data = {"options": '{"ocr_type": "basic"}'}
response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()
print(result)Recommended: Form data upload is the most efficient method with better performance and simpler integration.
import requests
import base64
url = "https://api.markdownconverters.com/api/v1/convert"
headers = {
"X-API-Key": "your_api_key_here",
"Content-Type": "application/json"
}
# Read and encode file
with open("/path/to/your/document.pdf", "rb") as file:
file_content = base64.b64encode(file.read()).decode('utf-8')
data = {
"source_type": "file",
"file": file_content,
"options": {
"ocr_type": "basic"
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)import requests
import base64
url = "https://api.markdownconverters.com/api/v1/convert"
headers = {
"X-API-Key": "your_api_key_here",
"Content-Type": "application/json"
}
with open("/path/to/your/document.pdf", "rb") as file:
file_content = base64.b64encode(file.read()).decode('utf-8')
data = {
"source_type": "file",
"file": file_content,
"options": {
"ocr_type": "advanced",
"extract_images": True,
"preserve_formatting": True
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Convert content directly from a webpage URL. Perfect for scraping and converting web content to Markdown.
import requests
url = "https://api.markdownconverters.com/api/v1/convert"
headers = {
"X-API-Key": "your_api_key_here",
"Content-Type": "application/json"
}
data = {
"source_type": "url",
"url": "https://example.com/article",
"options": {
"include_links": True,
"clean_html": True
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)import requests
url = "https://api.markdownconverters.com/api/v1/convert"
headers = {
"X-API-Key": "your_api_key_here",
"Content-Type": "application/json"
}
data = {
"source_type": "url",
"url": "https://example.com/article",
"options": {
"user_agent": "Mozilla/5.0 (compatible; MarkdownConverter/1.0)",
"include_links": True,
"extract_images": True
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Convert multiple files in a single request for improved efficiency and reduced API calls.
import requests
import base64
url = "https://api.markdownconverters.com/api/v1/batch-convert"
headers = {
"X-API-Key": "your_api_key_here",
"Content-Type": "application/json"
}
# Read and encode files
with open("document1.pdf", "rb") as file1:
content1 = base64.b64encode(file1.read()).decode('utf-8')
with open("document2.docx", "rb") as file2:
content2 = base64.b64encode(file2.read()).decode('utf-8')
data = {
"files": [
{
"filename": "document1.pdf",
"content": content1,
"options": {
"ocr_type": "basic"
}
},
{
"filename": "document2.docx",
"content": content2,
"options": {
"preserve_formatting": True
}
}
]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Check the status of your conversion jobs and retrieve results when ready.
import requests
url = "https://api.markdownconverters.com/api/v1/status/job-id-here"
headers = {"X-API-Key": "your_api_key_here"}
response = requests.get(url, headers=headers)
result = response.json()
print(result)import requests
url = "https://api.markdownconverters.com/api/v1/download/job-id-here"
headers = {"X-API-Key": "your_api_key_here"}
response = requests.get(url, headers=headers)
with open("converted-document.md", "wb") as f:
f.write(response.content)
print("File downloaded successfully!"){
"conversion_id": "550e8400-e29b-41d4-a716-446655440000",
"original_filename": "document.pdf",
"markdown_url": "https://storage.example.com/converted/document.pdf.md?token=...",
"markdown_content": "# Document Title\n\nFull markdown content here...",
"sas_expiry_at": "2025-09-24T16:00:00.000Z",
"status": "completed",
"metadata": {
"original_size_bytes": 12345,
"file_extension": ".pdf",
"markdown_size_bytes": 6789,
"word_count": 1234,
"estimated_reading_time_minutes": 6,
"conversion_options": {...},
"content_type": "document",
"conversion_time_ms": 1500
},
"file_size": 12345,
"conversion_time_ms": 1500,
"created_at": "2025-09-23T16:00:00.000Z"
}New in v2.1.0: The markdown_content field is now always included in responses - no need to specify include_content: true.
{
"job_id": "conv_1234567890abcdef",
"status": "processing",
"progress": 65,
"estimated_completion": "2024-01-15T10:30:00Z",
"message": "OCR processing in progress..."
}{
"error": "invalid_file_format",
"message": "Unsupported file format. Please use PDF, DOCX, or other supported formats.",
"supported_formats": ["pdf", "docx", "xlsx", "pptx", "html", "epub"]
}Use direct file upload for better performance:
# Recommended approach curl -F "file=@document.pdf" \ -H "X-API-Key: your_api_key" \ ...
More efficient than Base64 encoding
Markdown content is now always included:
# No need for include_content parameter response.markdown_content // Always present
Available immediately in v2.1.0+
For Base64 uploads (still supported):
# Encode file to Base64 base64 -i document.pdf
Handle rate limits gracefully:
# Add retry logic for 429 responses curl --retry 3 --retry-delay 5