Convert PDF to Markdown: A Developer's Guide Using REST API

A complete developer guide to converting PDFs to clean Markdown using REST APIs — with curl and Python code examples.

Why Convert PDF to Markdown?

If you're building a knowledge base, a RAG system, or a documentation platform, you've hit this problem: PDFs are terrible for downstream processing. They preserve visual layout but destroy semantic structure. Headings become bold text. Tables become whitespace-separated characters. Links become underlined strings.

Converting PDF to Markdown solves this. Markdown preserves heading hierarchy, list structure, links, and tables in a format that LLMs, static site generators, and CMS platforms actually understand. But doing it right — especially at scale — requires more than a regex hack.

This guide shows you how to convert PDF to Markdown using a REST API, with working code examples in curl and Python. We'll use the DocuMind API (available on RapidAPI) as the reference implementation, but the patterns apply to any PDF-to-Markdown converter API.

The Problem with Client-Side PDF-to-Markdown Conversion

Before we jump into the API approach, let's understand why most developers end up looking for a cloud solution in the first place.

What Client Libraries Get Wrong

Python libraries like pdfplumber, PyMuPDF, or pdf2md work fine for simple, text-based PDFs. But they break down when you encounter:

You end up writing hundreds of lines of heuristics and still getting inconsistent results.

The API Approach

A PDF to Markdown converter API handles all of this server-side with trained models. You send a file, get back clean Markdown. No model hosting, no GPU requirements, no maintenance burden.

The DocuMind Convert Endpoint

DocuMind provides a /convert endpoint that accepts PDF files and returns content in your target format — Markdown, HTML, or plain text.

POST https://api.tokenall.net.cn/documind/api/v1/convert

Converting PDF to Markdown with curl

Parameter	Type	Required	Description
`file`	multipart/form-data	Yes	The PDF file to convert
`target_format`	string	No	`markdown` (default), `html`, or `text`

# Convert a single PDF to Markdown
curl -X POST "https://api.tokenall.net.cn/documind/api/v1/convert" \
  -H "X-API-Key: YOUR_RAPIDAPI_KEY" \
  -F "file=@quarterly-report.pdf" \
  -F "target_format=markdown"

{
  "content": "# Quarterly Report Q3 2026\n\n## Revenue Summary\n\nTotal revenue reached **$4.2M**...\n\n| Metric | Q2 | Q3 |\n|--------|-----|-----|\n| ARR | $3.4M | $4.2M |\n",
  "pages_processed": 12,
  "format": "markdown"
}

Notice how tables, headings, and lists are all properly structured — that's the difference between a model-powered API and naive text extraction.

Converting PDF to Markdown with Python

import requests
import os
from pathlib import Path

class PDFToMarkdownConverter:
    """Convert PDF files to clean Markdown using the DocuMind API."""

    BASE_URL = "https://api.tokenall.net.cn/documind/api/v1"

    def __init__(self, api_key: str):
        self.headers = {"X-API-Key": api_key}

    def convert_file(self, file_path: str, target_format: str = "markdown") -> str:
        """Convert a single PDF file to the target format."""
        with open(file_path, "rb") as f:
            response = requests.post(
                f"{self.BASE_URL}/convert",
                headers=self.headers,
                files={"file": f},
                data={"target_format": target_format}
            )
        response.raise_for_status()
        return response.json()["content"]

    def convert_directory(self, dir_path: str, output_dir: str = None):
        """Batch convert all PDFs in a directory."""
        output_dir = output_dir or f"{dir_path}_markdown"
        Path(output_dir).mkdir(parents=True, exist_ok=True)

        results = []
        for pdf_file in Path(dir_path).glob("*.pdf"):
            try:
                markdown = self.convert_file(str(pdf_file))
                output_path = Path(output_dir) / f"{pdf_file.stem}.md"
                output_path.write_text(markdown, encoding="utf-8")
                results.append({"file": pdf_file.name, "status": "success"})
            except Exception as e:
                results.append({"file": pdf_file.name, "status": "error", "error": str(e)})
        return results

# Usage
converter = PDFToMarkdownConverter(api_key=os.environ["DOCUMIND_API_KEY"])
markdown = converter.convert_file("research-paper.pdf")
print(markdown[:500])

Building a PDF-to-Markdown Pipeline

In real applications, conversion is just one step. Here's how to chain it into a larger workflow:

Pattern: Ingest → Convert → Index

class DocumentPipeline:
    def __init__(self, api_key: str):
        self.headers = {"X-API-Key": api_key}
        self.base_url = "https://api.tokenall.net.cn/documind/api/v1"

    def process_for_knowledge_base(self, file_path: str):
        """Convert PDF to Markdown and extract metadata for indexing."""
        # Step 1: Convert to Markdown for display
        with open(file_path, "rb") as f:
            resp = requests.post(
                f"{self.base_url}/convert",
                headers=self.headers,
                files={"file": f},
                data={"target_format": "markdown"}
            )
        markdown_content = resp.json()["content"]

        # Step 2: Extract raw text for search indexing
        with open(file_path, "rb") as f:
            resp = requests.post(
                f"{self.base_url}/extract",
                headers=self.headers,
                files={"file": f}
            )
        raw_text = resp.json()["text"]

        # Step 3: Generate AI summary for preview
        with open(file_path, "rb") as f:
            resp = requests.post(
                f"{self.base_url}/summarize",
                headers=self.headers,
                files={"file": f},
                data={"summary_length": "brief"}
            )
        summary = resp.json()["summary"]

        return {
            "markdown": markdown_content,
            "raw_text": raw_text,
            "summary": summary,
            "source": file_path
        }

This gives you Markdown for display, raw text for full-text search, and a summary for preview cards — all from a single API integration.

Key Considerations for PDF to Markdown Conversion

Handling Large Files

DocuMind handles documents up to 50MB on the PRO plan. For larger files, split them first using a library like PyPDF2 before sending to the API.

Preserving Tables

Tables are where most conversions fail. DocuMind uses vision models to detect table structures and convert them to proper Markdown table syntax. Always test with your actual documents before committing to a provider.

Error Handling in Production

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=10))
def convert_with_retry(converter, file_path):
    return converter.convert_file(file_path)

Pricing and Plans

The BASIC plan is enough to evaluate conversion quality with your own documents.

Conclusion

Converting PDF to Markdown via API eliminates the complexity of client-side document parsing. You get heading detection, table preservation, and proper formatting without maintaining ML models or fighting with layout heuristics.

The DocuMind API makes it a single POST request. Start with the free BASIC plan, test with your documents, and scale when you're ready.

Plan	Requests/Month	Price	Best For
BASIC	100	Free	Testing & prototyping
PRO	5,000	$29/mo	Small teams & MVPs
ULTRA	25,000	$99/mo	Production workloads