# PDF to Markdown + RAG Chunks: LLM-Ready PDF Text (`atesen-software/pdf-to-markdown-rag`) Actor

Convert PDF URLs to clean Markdown and page-aware RAG chunks. Detects headings and tables, strips repeated headers and footers, adds a SHA-256 per document and chunk. Text-layer PDFs only: scanned PDFs get a clear free warning instead of a guess.

- **URL**: https://apify.com/atesen-software/pdf-to-markdown-rag.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Categories:** AI, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.40 / 1,000 pdf page converteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## PDF to Markdown + RAG Chunks: LLM-Ready PDF Text

Give it PDF links. Get clean **Markdown** and **RAG chunks** back, with page numbers, headings, tables and SHA-256 hashes. A fast **PDF text extraction API** for AI pipelines, search indexes, knowledge bases and document archives. No browser, no proxy, no OCR guessing.

### What it does

For every PDF URL the Actor:

1. Downloads the file safely (size limit, time limit, redirects checked, no internal addresses) and computes the **SHA-256 of the PDF**.
2. Reads the text layer and rebuilds the reading order: lines, paragraphs, bullet and numbered lists.
3. Finds **headings** from the font size and writes them as Markdown headings (`#`, `##`, `###`).
4. Turns cleanly aligned columns into **Markdown tables**.
5. Removes **running headers, footers and page numbers** that repeat on the pages.
6. Cuts the text into **page-aware RAG chunks**: each chunk knows its heading path, first and last page, size in characters and approximate tokens, and has its own SHA-256 and a stable id. Chunks never exceed the size you set, start at headings, and can overlap inside a section.

Use it for **LLM-ready PDF** input to vector databases (Pinecone, Qdrant, Weaviate, pgvector), RAG and agent pipelines, document search, contract and report processing, and change detection (the hashes tell you which files and which chunks changed, so you re-embed only what changed).

### What it does not do (read this first)

- **No OCR.** The PDF must contain a text layer (most PDFs made from Word, LaTeX, web pages or accounting software do). A PDF that is only scanned images returns a clear `scanned` row with an explanation. It is free, and nothing is guessed.
- **Password-protected PDFs** return a `password` row. Free. Remove the password first.
- **Multi-column pages are read line by line across the columns**, so sentences of neighbouring columns can mix on two-column papers and forms. One-column documents work best.
- **Tables** are detected only when 3 or more lines have cleanly aligned columns with short cells. Drawn grid lines, merged cells and tables inside images are not detected; their text stays as plain lines. Please check important tables.
- **Headings** are found from the font size. Bold headings that are not larger than the body text are not found.
- Images, figures, links, comments, form fields, bold and italic are not part of the output. Rotated text is skipped.
- Pages are read in order; the Actor does not understand the meaning of the document.

### Input

```json
{
  "pdfUrls": ["https://www.irs.gov/pub/irs-pdf/fw9.pdf"],
  "outputFormat": "both",
  "pageRange": "3-6",
  "chunkSize": 1500,
  "chunkOverlap": 200
}
```

| Field | What it does |
|---|---|
| `pdfUrls` | Direct links to PDF files (up to 500 per run). Public links only, no login. Duplicates are processed once. |
| `outputFormat` | `markdown` (one row per PDF), `chunks` (summary row plus one row per chunk) or `both`. |
| `pageRange` | For example `1-5, 8, 10-`. Empty means all pages. Only selected pages are processed and charged. |
| `chunkSize`, `chunkOverlap` | Characters per chunk (200 to 8000) and repeated characters between chunks of one section. |
| `headingAware`, `detectTables`, `stripHeadersFooters` | Switch the heading, table and header/footer logic on or off. |
| `includePageMarkers` | Adds `<!-- page 3 -->` comments to the Markdown. |
| `maxPdfMb`, `maxPagesPerDocument` | Safety limits (up to 50 MB and 500 pages per PDF). A longer PDF gets a free error row; use `pageRange` to convert part of it. |

### Output

One dataset row per PDF (`type: "document"`), followed by one row per chunk (`type: "chunk"`). The Markdown is also saved as a file (`document-0001.md`) in the key-value store.

By default, the document row identifies the saved file with `markdownKey`. Open your run's **Key-value Store** and use that key to retrieve the file. Enable `shareMarkdownLinks` only if you want a link that anyone with the URL can open. Keep these links out of public logs. Access to the underlying Apify storage follows your account's sharing settings.

```json
{
  "type": "document",
  "index": 1,
  "sourceUrl": "https://www.irs.gov/pub/irs-pdf/fw9.pdf",
  "status": "ok",
  "sha256": "2d420cbb4123...",
  "title": "Form W-9 (Rev. March 2024)",
  "pageCount": 6,
  "pagesProcessed": 4,
  "pagesWithText": 4,
  "pagesWithoutText": [],
  "pagesCharged": 4,
  "headingCount": 5,
  "tableCount": 0,
  "chunkCount": 30,
  "markdown": "## What Is FATCA Reporting? ...",
  "markdownUrl": null
}
```

```json
{
  "type": "chunk",
  "chunkId": "2d420cbb4123-0003",
  "chunkIndex": 3,
  "documentSha256": "2d420cbb4123...",
  "heading": "Line 3a",
  "headingPath": ["What Is FATCA Reporting?", "Line 3a"],
  "pageStart": 3,
  "pageEnd": 3,
  "pages": [3],
  "approxTokens": 218,
  "overlapChars": 0,
  "text": "### Line 3a\n\nCheck the appropriate box ...",
  "sha256": "..."
}
```

#### Status values

| `status` | Meaning | Charged |
|---|---|---|
| `ok` | Converted. | Yes, per page with a text layer |
| `scanned` | No text layer (scanned images). OCR is not supported. | No |
| `password` | The PDF is password-protected. | No |
| `failed` | Download blocked or failed, not a PDF, damaged, too large, too many pages, or time limit. The `error` field says why. | No |
| `skipped` | Not processed because the maximum cost per run was reached. | No |

Pages without a text layer inside an otherwise normal PDF are listed in `pagesWithoutText` and are not charged.

### Pricing

Pay per event: one **page** event for each PDF page that has a text layer and was converted. The current price is shown on the Pricing tab. Failed, scanned, password-protected and skipped PDFs, and pages without text, are free. The price does not depend on the output format. Set a maximum cost per run to cap spending: the Actor stops cleanly and marks the remaining PDFs `skipped`.

**Maximum items is a hard cap on charged rows.** Set `maxItems` in the run options (or `?maxItems=` in the API) and the run stops after that many charged pages: it never charges more pages than that number. A document that would pass the cap is cut at that page (its row says so) and later documents get a free skipped row. Leave it empty for no cap.

### Safety

The Actor only fetches `http` and `https` URLs. It refuses internal, private, loopback, link-local and cloud-metadata addresses, host names that resolve to them (the address that was checked is the address that is used), redirects to such addresses or to other protocols, URLs with a user name or password, and files above the size limit. No cookies and no credentials are sent. You are responsible for having the right to process the documents you give it.

### Use via API

One request runs the Actor, waits for it and returns the dataset items as JSON. Send your token in the `Authorization` header, not in the URL:

```bash
curl -X POST "https://api.apify.com/v2/acts/atesen-software~pdf-to-markdown-rag/run-sync-get-dataset-items?timeout=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pdfUrls":["https://www.irs.gov/pub/irs-pdf/fw9.pdf"],"pageRange":"3-6"}'
```

The synchronous endpoint waits up to 300 seconds. For longer jobs start a run with `POST https://api.apify.com/v2/acts/atesen-software~pdf-to-markdown-rag/runs` and read the dataset when it finishes.

**JavaScript** (`npm install apify-client`):

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('atesen-software/pdf-to-markdown-rag').call({ pdfUrls: ["https://www.irs.gov/pub/irs-pdf/fw9.pdf"], pageRange: "3-6" });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with AI agents (MCP)

Claude Desktop, Cursor, VS Code and other MCP clients can call this Actor as a tool through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Load only this Actor with:

```text
https://mcp.apify.com?tools=atesen-software/pdf-to-markdown-rag
```

Client config (sign in with Apify OAuth when the browser opens, or add an `Authorization: Bearer <APIFY_TOKEN>` header instead):

```json
{
  "mcpServers": {
    "apify": { "url": "https://mcp.apify.com?tools=atesen-software/pdf-to-markdown-rag" }
  }
}
```

Then ask in plain words, for example: "Convert pages 3 to 6 of https://www.irs.gov/pub/irs-pdf/fw9.pdf to Markdown chunks." The agent fills the same input fields you see on the Input tab, and runs are billed to your Apify account at the prices on the Pricing tab.

### FAQ

**Can it read scanned PDFs?** No. It tells you so, for free. Use an OCR Actor first, then run the resulting searchable PDF through this Actor.

**Why are chunks measured in characters?** Characters are exact and tokenizer-independent. `approxTokens` is characters divided by 4; pick a `chunkSize` that fits your embedding model.

**How do I keep my vector index current?** Store `documentSha256` and each chunk `sha256`. When a PDF changes, only the chunks whose hash is new need embedding.

**Does the page number refer to the printed number?** No, it is the position in the file (page 1 is the first page of the PDF).

**Which library reads the PDFs?** Mozilla pdf.js (Apache-2.0). The layout, heading, table and chunk logic is this Actor's own.

### Related actors

- [URL to Markdown Converter for RAG: Pages, PDFs & Sitemaps](https://apify.com/atesen-software/url-to-markdown-rag)
- [Website to LLM-Ready Dataset: Markdown & Chunks for RAG](https://apify.com/atesen-software/llm-dataset-builder)
- [Audio & Video Transcriber API: Speech to Text, SRT, VTT](https://apify.com/atesen-software/audio-video-transcriber)

# Actor input Schema

## `pdfUrls` (type: `array`):

Direct public links to PDFs you have permission to process, one per line (up to 500 per run). Do not include access tokens or other secrets in the URL. The example is a public US government form.

## `outputFormat` (type: `string`):

Markdown: one dataset row per PDF with the full Markdown. Chunks: one summary row per PDF plus one row per RAG chunk. Both: the Markdown and the chunk rows. The price is the same for all three.

## `shareMarkdownLinks` (type: `boolean`):

When enabled, anyone with a generated link can open that Markdown file. Leave off to retrieve the file by its record key in your run's Key-value Store.

## `pageRange` (type: `string`):

Only convert some pages, for example 1-5, 8, 10- (page numbers start at 1, 10- means page 10 to the end). Empty = all pages. Only the selected pages are processed and charged.

## `chunkSize` (type: `integer`):

Maximum characters per RAG chunk, including the repeated overlap. About 4 characters are 1 token, so 1500 is roughly 375 tokens. Chunks end at headings, paragraphs and sentences where possible.

## `chunkOverlap` (type: `integer`):

How many characters of the end of the previous chunk are repeated at the start of the next chunk of the same section. Never more than half the chunk size. 0 = no overlap.

## `headingAware` (type: `boolean`):

Find headings from the font size (larger than the body text) and write them as Markdown headings. Every heading also starts a new chunk, and each chunk gets its heading path. Headings that are bold but not larger are not detected.

## `detectTables` (type: `boolean`):

Turn 3 or more lines of cleanly aligned columns into Markdown tables. Tables without aligned columns, merged cells and drawn grid lines are not detected; their text stays as plain lines.

## `stripHeadersFooters` (type: `boolean`):

Remove text that repeats in the top or bottom margin of at least half of the pages (running titles, page numbers). Needs 3 or more pages.

## `includePageMarkers` (type: `boolean`):

Insert an HTML comment like  before the first text of every page. Chunks always carry their page numbers, with or without this option.

## `maxPdfMb` (type: `integer`):

PDF files larger than this are not downloaded (free error row). The upper limit is 50 MB.

## `maxPagesPerDocument` (type: `integer`):

A PDF with more selected pages than this gets a free error row instead of a conversion. Use the page range to convert part of a long document. The upper limit is 500.

## Actor input object example

```json
{
  "pdfUrls": [
    "https://www.irs.gov/pub/irs-pdf/fw9.pdf"
  ],
  "outputFormat": "both",
  "shareMarkdownLinks": false,
  "pageRange": "3-6",
  "chunkSize": 1500,
  "chunkOverlap": 200,
  "headingAware": true,
  "detectTables": true,
  "stripHeadersFooters": true,
  "includePageMarkers": false,
  "maxPdfMb": 50,
  "maxPagesPerDocument": 500
}
```

# Actor output Schema

## `documents` (type: `string`):

One row per PDF: status, error, page counts, SHA-256, title, Markdown and its file link

## `chunks` (type: `string`):

One row per chunk: text, heading path, page numbers, size and SHA-256

## `files` (type: `string`):

document-0001.md, document-0002.md, ... in the key-value store of the run

## `summary` (type: `string`):

Counts of converted, scanned, password-protected and failed PDFs, pages charged and why the run stopped

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "pdfUrls": [
        "https://www.irs.gov/pub/irs-pdf/fw9.pdf"
    ],
    "pageRange": "3-6"
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/pdf-to-markdown-rag").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "pdfUrls": ["https://www.irs.gov/pub/irs-pdf/fw9.pdf"],
    "pageRange": "3-6",
}

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/pdf-to-markdown-rag").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "pdfUrls": [
    "https://www.irs.gov/pub/irs-pdf/fw9.pdf"
  ],
  "pageRange": "3-6"
}' |
apify call atesen-software/pdf-to-markdown-rag --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/pdf-to-markdown-rag"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jVZg8QWRZq3pVPfVd/builds/DBVdJaVwIhnes3Tye/openapi.json
