Convert PDF to Markdown with one API call

POST /v1/convert converts a PDF to Markdown in one call, and the response carries the text. The direct call reads the PDF's text layer with MarkItDown, so it returns plain text without headings and without OCR.

For headings, reading order and tables, or for scanned pages, send the PDF to the queue. The queue runs Docling with OCR.

curl

curl -F "file=@report.pdf;type=application/pdf" https://api.flatmark.dev/v1/convert

The response is JSON. The text is in markdown:

{"markdown": "Quarterly report\n\nRevenue grew 8 percent in EMEA and 13 percent in APAC.\n\n...", "meta": {"filename": "report.pdf"}}

Python

import httpx

with open("report.pdf", "rb") as fh:
    resp = httpx.post(
        "https://api.flatmark.dev/v1/convert",
        files={"file": ("report.pdf", fh, "application/pdf")},
        headers={"X-API-Key": "YOUR_KEY"},  # optional
        timeout=60,
    )
resp.raise_for_status()
markdown = resp.json()["markdown"]
if not markdown.strip():
    print("No text layer. Send this file to the queue for OCR.")
print(markdown)

Without a key, the call runs anonymously and costs nothing, within the rate limit per IP address. With a key, it costs 1 credit.

What the direct call returns for a PDF

• Text in the order of the PDF's text layer, without # headings.
• Tables mostly as lines of text, not as Markdown tables.
• For a scan, an empty markdown field with status 200. Check for empty output in your code.
• For a file over 8 MB, an error (413). Send it to the queue.

Next step

Convert a PDF in the browser, up to 4 MB and without an account.

FAQ

Can flatmark read scanned PDFs?

Only through the queue, which runs OCR. The direct call reads the text layer, so a scan comes back empty. OCR quality depends on the scan.

What does a PDF conversion cost?

Without a key, 10 direct calls a day are free. With a key, a direct call costs 1 credit and a queued file 10 credits, whatever the page count. Plans are on the pricing page.