---
title: "PDF-to-Markdown API"
canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-to-markdown-api/"
md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-to-markdown-api.md"
last_updated: "2026-07-06T00:00:00.000Z"
description: "Convert PDF files to Markdown using Nutrient DWS Processor API. Export PDFs as Markdown for content migration, indexing, and lightweight text-based workflows."
---

# PDF-to-Markdown API

Use the PDF-to-Markdown API to convert PDF documents to Markdown. Nutrient DWS Processor API supports Markdown output for workflows such as content migration, indexing, review, and text-based processing.

The [`/build` endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) handles PDF-to-Markdown conversion. Add the source PDF as a `parts` item, and set `output.type` to `markdown`.

For signup, pricing, and task-level examples, refer to the [PDF-to-Markdown API task page](https://www.nutrient.io/api/pdf-to-md-api/).

For advanced or retrieval-augmented generation (RAG)-grade extraction — including layout-aware structured extraction, bounding boxes, tables, key-value pairs, schema-shaped JSON, citations, confidence scores, or whole-document Markdown optimized for retrieval pipelines — use the [DWS Data Extraction API](https://www.nutrient.io/guides/dws-data-extraction.md).

## Convert a PDF to Markdown

The following example converts `document.pdf` to `result.md`:

### Shell

### Shell (Windows)

### Java

### C#

### JavaScript

### Python

### PHP

### HTTP

## Convert a PDF from a URL

For remotely hosted source files, send a JSON request and pass the source URL in `parts[].file.url`. Use this instructions object:

```json

{
  "parts": [
    {
      "file": {
        "url": "https://example.com/document.pdf"
      }
    }
  ],
  "output": {
    "type": "markdown"
  }
}

```

### Shell

Run this request to convert a PDF from a URL:

```bash

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer $NUTRIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parts": [
      {
        "file": {
          "url": "https://example.com/document.pdf"
        }
      }
    ],
    "output": {
      "type": "markdown"
    }
  }' \
  -o result.md

```

## Convert selected PDF pages

Use `parts[].pages` to convert only a page range from the source PDF. Page indexes are zero-based, and negative values count from the end of the document.

The following example converts the first three pages to Markdown:

```json

{
  "parts": [
    {
      "file": "document",
      "pages": {
        "start": 0,
        "end": 2
      }
    }
  ],
  "output": {
    "type": "markdown"
  }
}

```

The `end` value is inclusive, so `{ "start": 0, "end": 2 }` includes pages zero, one, and two.

## Convert password-protected PDFs

If the source PDF is password-protected, include the password on the part. Use this instructions object:

```json

{
  "parts": [
    {
      "file": "protected_document",
      "password": "document-password"
    }
  ],
  "output": {
    "type": "markdown"
  }
}

```

Nutrient DWS Processor API uses the password only to open the source document for processing.

## Convert scanned PDFs

PDF-to-Markdown conversion works best with born-digital PDFs that already contain selectable text. For scanned or image-only PDFs, run optical character recognition (OCR) first to create a searchable PDF, and then convert the searchable result to Markdown.

Use this instructions object to run OCR:

```json

{
  "parts": [
    {
      "file": "scanned_document"
    }
  ],
  "actions": [
    {
      "type": "ocr",
      "language": "english"
    }
  ]
}

```

After OCR, send the searchable PDF to a second `/build` request with `output.type` set to `markdown`.

For advanced scanned-document extraction, multilingual OCR, layout analysis, and RAG ingestion, use the [DWS Data Extraction API](https://www.nutrient.io/guides/dws-data-extraction.md).

## Compare Processor API Markdown and DWS Data Extraction API Markdown

Use Processor API PDF-to-Markdown conversion when you need Markdown as an output format in a `/build` workflow.

Use DWS Data Extraction API when you need advanced extraction features, such as:

- Markdown optimized for RAG ingestion

- Typed document elements with bounding boxes

- Table and key-value extraction

- Schema-shaped JSON extraction

- Citations and confidence scores

- Processing modes for text, OCR structure extraction, AI understanding, or vision language model (VLM)-augmented extraction

For extraction-focused workflows, refer to the [DWS Data Extraction API](https://www.nutrient.io/guides/dws-data-extraction.md) guide.

## Combine PDF-to-Markdown conversion with other processing

The `/build` endpoint can assemble or prepare a PDF before it converts the file to Markdown. For example, you can merge multiple PDFs and convert the merged output to Markdown.

Use this instructions object to merge two PDFs and convert them to Markdown:

```json

{
  "parts": [
    {
      "file": "cover"
    },
    {
      "file": "body"
    }
  ],
  "output": {
    "type": "markdown"
  }
}

```

You can also extract selected pages before conversion with `parts[].pages`.

## Reference

A PDF-to-Markdown request uses the Build API `output` object with Markdown output:

```typescript

type MarkdownOutput = {
  type: "markdown",
};

type FilePart = {
  // Multipart field name, or a remote URL object.
  file: string | { url: string },

  // Optional password for encrypted input PDFs.
  password?: string,

  // Optional page range to convert.
  pages?: {
    start?: number,
    end?: number,
  },
};

type BuildInstructions = {
  parts: FilePart[],
  output: MarkdownOutput,
};

```

## Related API reference operations

- Refer to the [build document endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) API reference to convert PDFs to Markdown and combine conversion with page selection or document assembly.

## Related guides

- Refer to the [PDF-to-HTML API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-to-html-api.md) guide.

- Refer to the [Markdown-to-PDF API](https://www.nutrient.io/guides/dws-processor/tools-and-api/markdown-to-pdf-api.md) guide.

- Refer to the [PDF-to-Office API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-to-office-api.md) guide.

- Refer to the [PDF OCR API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-ocr-api.md) guide.

- Refer to the [PDF merge API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-merge-api.md) guide.

- Refer to the [PDF split API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-split-api.md) guide.

- Refer to the [DWS Data Extraction API](https://www.nutrient.io/guides/dws-data-extraction.md) guide.

- Refer to the [tools and APIs](https://www.nutrient.io/guides/dws-processor/tools-and-api.md) guide.
---

## Related pages

- [Image-to-PDF API](/guides/dws-processor/tools-and-api/image-to-pdf-api.md)
- [Document-to-image API](/guides/dws-processor/tools-and-api/document-to-image-api.md)
- [DOCX templating API](/guides/dws-processor/tools-and-api/docx-templating-api.md)
- [Import XFDF annotations API](/guides/dws-processor/tools-and-api/import-xfdf-annotations-api.md)
- [Analyze Build API](/guides/dws-processor/tools-and-api/analyze-build-api.md)
- [Office-to-PDF API](/guides/dws-processor/tools-and-api/office-to-pdf-api.md)
- [Tools and APIs](/guides/dws-processor/tools-and-api.md)
- [Import Instant JSON API](/guides/dws-processor/tools-and-api/import-instant-json-api.md)
- [Markdown-to-PDF API](/guides/dws-processor/tools-and-api/markdown-to-pdf-api.md)
- [PDF flatten API](/guides/dws-processor/tools-and-api/pdf-flatten-api.md)
- [PDF linearization API](/guides/dws-processor/tools-and-api/pdf-linearization-api.md)
- [PDF merge API](/guides/dws-processor/tools-and-api/pdf-merge-api.md)
- [PDF digital signature API](/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md)
- [PDF optimization API](/guides/dws-processor/tools-and-api/pdf-optimization-api.md)
- [PDF form filling API](/guides/dws-processor/tools-and-api/pdf-form-filling-api.md)
- [PDF security API](/guides/dws-processor/tools-and-api/pdf-security-api.md)
- [PDF rotate API](/guides/dws-processor/tools-and-api/pdf-rotate-api.md)
- [PDF page manipulation API](/guides/dws-processor/tools-and-api/pdf-page-manipulation-api.md)
- [PDF-to-image API](/guides/dws-processor/tools-and-api/pdf-to-image-api.md)
- [PDF split API](/guides/dws-processor/tools-and-api/pdf-split-api.md)
- [PDF watermark API](/guides/dws-processor/tools-and-api/pdf-watermark-api.md)
- [PDF OCR API](/guides/dws-processor/tools-and-api/pdf-ocr-api.md)
- [PDF-to-HTML API](/guides/dws-processor/tools-and-api/pdf-to-html-api.md)
- [PDF-to-PDF/A API](/guides/dws-processor/tools-and-api/pdf-to-pdfa-api.md)
- [PDF generator API](/guides/dws-processor/tools-and-api/pdf-generator-api.md)
- [PDF/UA auto-tagging API](/guides/dws-processor/tools-and-api/pdfua-api.md)
- [PDF-to-Office API](/guides/dws-processor/tools-and-api/pdf-to-office-api.md)
- [Redaction API](/guides/dws-processor/tools-and-api/redaction-api.md)