Convert single files to AI-ready Markdown format
POST /api/v1/convertPOSTThe file conversion endpoint allows you to convert a single document to AI-ready Markdown format. It supports form data uploads (recommended), Base64-encoded file content, and URL-based conversion, making it flexible for various integration scenarios.
curl -X POST https://api.markdownconverters.com/api/v1/convert \
-H "X-API-Key: your_api_key_here" \
-F "file=@document.pdf" \
-F 'options={"ocr_type": "basic"}'{
"source_type": "file",
"file": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovQ29udGVudHMgNCAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL0xlbmd0aCAvRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeAErVAhUKFQwULCyUsrPTSxTMFOw0lEoSCwGwvTk4lLFMo0FiQWJyQAA//8AAP//AwAKrQc0CmVuZHN0cmVhbQplbmRvYmoKNSAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTEKL0Jhc2VGb250IC9IZWx2ZXRpY2EKPj4KZW5kb2JqCnhyZWYKMCA2CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKMDAwMDAwMDIwNCAwMDAwMCBuIAowMDAwMDAwMzEwIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgNgovUm9vdCAxIDAgUko+PgpzdGFydHhyZWYKNDA5CiUlRU9G",
"options": {
"ocr_type": "basic"
}
}curl -X POST https://api.markdownconverters.com/api/v1/convert \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"source_type": "file",
"file": "base64_encoded_file_content",
"options": {
"ocr_type": "basic"
}
}'{
"source_type": "url",
"url": "https://example.com/document.pdf",
"options": {
"ocr_type": "advanced"
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
| source_type | string | Yes | Either "file" or "url" |
| file | string | Conditional | Base64-encoded file content (required if source_type is "file") |
| url | string | Conditional | URL to downloadable file (required if source_type is "url") |
| options | object | No | Conversion options (see below) |
| Option | Type | Default | Description |
|---|---|---|---|
| ocr_type | string | "basic" | "basic" or "advanced" OCR processing |
| preserve_formatting | boolean | true | Maintain original document formatting |
| output_format | string | "markdown" | Output format (currently only "markdown") |
{
"job_id": "conv_1234567890abcdef",
"status": "completed",
"markdown_content": "# Sample Document\n\nThis is the extracted text from your PDF document.\n\n## Section 1\n\nContent from the first section with **bold** and *italic* formatting preserved.\n\n- List item 1\n- List item 2\n- List item 3\n\n## Section 2\n\nAdditional content with proper heading structure for AI processing.",
"metadata": {
"source_type": "file",
"file_size": 2048,
"pages": 1,
"processing_time_ms": 1250,
"ocr_confidence": 0.98
},
"sas_url": "https://storage.azure.com/converted/conv_1234567890abcdef.md?sp=r&st=2024-01-01T00:00:00Z&se=2024-01-02T00:00:00Z&spr=https&sv=2022-11-02&sr=b&sig=...",
"created_at": "2024-01-01T12:00:00Z",
"expires_at": "2024-01-02T12:00:00Z"
}| Field | Type | Description |
|---|---|---|
| job_id | string | Unique identifier for this conversion job |
| status | string | Job status: "completed", "processing", or "failed" |
| markdown_content | string | Extracted content in Markdown format |
| metadata | object | Processing metadata and statistics |
| sas_url | string | Temporary download URL for the converted file |
{
"error": "invalid_file_format",
"message": "The provided file format is not supported",
"details": {
"field": "file",
"code": "UNSUPPORTED_FORMAT",
"suggestion": "Please use one of the supported formats: PDF, Word, Excel, PowerPoint, HTML, or images"
},
"request_id": "req_1234567890abcdef"
}