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

Scanned or photographed PDFs

Documents with complex table layouts

Handwritten text or annotations

Multi-language or mixed-script documents

Charts and diagrams with data

Low-quality or faded documents

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.

Get Your API Key — $8.99/month Full API Reference

Related Resources

API Reference Documentation

Complete endpoint reference with request/response schemas

Build a RAG Knowledge Base

Use converted Markdown to build AI-powered search systems

Batch Conversion

Convert hundreds of files through the web interface

Pricing Plans

Compare API limits and features across all plans

Why Use a Document Conversion API?

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

Scanned or photographed PDFs

Documents with complex table layouts

Handwritten text or annotations

Multi-language or mixed-script documents

Charts and diagrams with data

Low-quality or faded documents

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.

Get Your API Key — $8.99/month Full API Reference

PDF to Markdown API

Why Use a Document Conversion API?

RAG Pipelines

CMS Migration

Document Processing

Data Extraction

API Overview & Authentication

Getting Your API Key

Rate Limits by Plan

Quick Start: Convert Your First PDF

Python Integration

Node.js / TypeScript Integration

AI Vision via API

When to Use AI Vision

Best Practices

Use retries with exponential backoff

Check file types before upload

Cache conversion results

Limit batch concurrency

Secure your API key

Get Started with the API

Related Resources

API Reference Documentation

Build a RAG Knowledge Base

Batch Conversion

Pricing Plans

Ship Markdown workflows with confidence

PDF to Markdown API

Why Use a Document Conversion API?

RAG Pipelines

CMS Migration

Document Processing

Data Extraction

API Overview & Authentication

Getting Your API Key

Rate Limits by Plan

Quick Start: Convert Your First PDF

Python Integration

Node.js / TypeScript Integration

AI Vision via API

When to Use AI Vision

Best Practices

Use retries with exponential backoff

Check file types before upload

Cache conversion results

Limit batch concurrency

Secure your API key

Get Started with the API

Related Resources

API Reference Documentation

Build a RAG Knowledge Base

Batch Conversion

Pricing Plans

Ship Markdown workflows with confidence