PDF to Markdown API
Use POST /v1/convert to turn a PDF into Markdown from your application. Send the file as multipart form data and authenticate with an API key. The service reads a usable text layer and can use OCR for scans or unreadable pages.
For an upload in your browser, use the PDF to Markdown converter. Its free mode extracts existing text without OCR. This guide covers the authenticated API, where conversions use credits.
1. Create an API key
Section titled “1. Create an API key”Sign in, open API keys, and create a key. Store it in an environment variable or secret manager. New accounts receive 500 free credits. See Authentication for key storage and rotation.
2. Send the PDF
Section titled “2. Send the PDF”The API base URL is https://api.md.tlelabs.com. The file field contains your PDF; ocr=auto lets the service use OCR when needed. Replace the example key with your own key.
curl -X POST 'https://api.md.tlelabs.com/v1/convert' \ -H 'Authorization: Bearer <YOUR_API_KEY>' \ -F 'file=@document.pdf' \ -F 'ocr=auto'import { readFile } from "node:fs/promises";
const form = new FormData();form.append("file", new Blob([await readFile("document.pdf")]), "document.pdf");form.append("ocr", "auto");
const response = await fetch("https://api.md.tlelabs.com/v1/convert", { method: "POST", headers: { Authorization: "Bearer <YOUR_API_KEY>" }, body: form,});const result = await response.json();console.log(result.markdown);import requests
with open("document.pdf", "rb") as file: response = requests.post( "https://api.md.tlelabs.com/v1/convert", headers={"Authorization": "Bearer <YOUR_API_KEY>"}, files={"file": file}, data={"ocr": "auto"}, )print(response.json()["markdown"])These are minimal request examples. Check the HTTP status before reading result.markdown: use response.ok in JavaScript or response.raise_for_status() in Python. The Python guide includes a complete example that checks the response and saves a Markdown file.
3. Choose how OCR is used
Section titled “3. Choose how OCR is used”ocr=off: read the existing text layer without OCR. A PDF containing only scans may fail with422 parse_failed.ocr=auto: use OCR for unreadable or scanned pages and pictures that need it, preserving readable text on other pages.ocr=force: request OCR for all pages. Use this when you intentionally want every page read by an OCR model.
ocr_model=auto uses the service’s configured model choices. Other models are listed in OCR models. The OCR-capable PDF size limit is 20 MB; ordinary request limits are described in Formats, pages and pricing.
Text-layer extraction costs 1 credit per page ($0.20 per 1,000 pages). OCR with ocr_model=auto costs 15 credits per OCR page ($3.00 per 1,000 pages). Inspect usage in the response for the pages and credits actually used; failed conversions are not charged.
4. Read Markdown and usage
Section titled “4. Read Markdown and usage”The default response is JSON with markdown, format, usage, metadata and warnings. Check the extracted content and warnings before adding it to a knowledge base or publishing it.
For Markdown as the response body, send Accept: text/markdown. Read the body as text and use the credit headers described in the Convert API reference; a plain-text response is not JSON.
PDF page positions do not always identify semantic headings, tables or reading order. Conversion makes the text reusable, but it does not guarantee an exact reconstruction of the page layout.
Handle errors before saving output
Section titled “Handle errors before saving output”Check HTTP status and the structured error code:
401: verify the API key.402 insufficient_credits: check your wallet before trying again.413: check file and page limits.422 parse_failed: the file could not be read; for a scan, consider enabling OCR.429: respectRetry-Afterand the concurrency limit.502 ocr_provider_error: an OCR provider failed; a failed conversion is not charged.
The complete response contract is in Errors and Convert a file. Uploaded content is processed by the service; see the Privacy Policy for processing and OCR provider details.