# PDF to Markdown API

> Convert text-layer or scanned PDFs to Markdown with the HTTP API, choose OCR options, check errors and read conversion usage.

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](https://md.tlelabs.com/pdf-to-markdown/). Its free mode extracts existing text without OCR. This guide covers the authenticated API, where conversions use credits.

## 1. Create an API key

Sign in, open [API keys](https://md.tlelabs.com/keys), and create a key. Store it in an environment variable or secret manager. New accounts receive 500 free credits. See [Authentication](https://md.tlelabs.com/docs/authentication/) for key storage and rotation.

## 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**

```sh
curl -X POST 'https://api.md.tlelabs.com/v1/convert' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'file=@document.pdf' \
  -F 'ocr=auto'
```

**JavaScript**

```js
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);
```

**Python**

```py
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](https://md.tlelabs.com/docs/guides/document-to-markdown-python/) includes a complete example that checks the response and saves a Markdown file.

## 3. Choose how OCR is used

- `ocr=off`: read the existing text layer without OCR. A PDF containing only scans may fail with `422 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](https://md.tlelabs.com/docs/ocr-models/). The OCR-capable PDF size limit is 20 MB; ordinary request limits are described in [Formats, pages and pricing](https://md.tlelabs.com/docs/formats-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

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](https://md.tlelabs.com/docs/convert/); 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

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`: respect `Retry-After` and the concurrency limit.
- `502 ocr_provider_error`: an OCR provider failed; a failed conversion is not charged.

The complete response contract is in [Errors](https://md.tlelabs.com/docs/errors/) and [Convert a file](https://md.tlelabs.com/docs/convert/). Uploaded content is processed by the service; see the [Privacy Policy](https://md.tlelabs.com/privacy/) for processing and OCR provider details.
