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 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.

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.

Convert a PDF to Markdown

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

curl -X POST https://api.nutrient.io/build \
  -H "Authorization: Bearer your_api_key_here" \
  -o result.md \
  --fail \
  -F file=@document.pdf \
  -F instructions='{
      "parts": [
        {
          "file": "file"
        }
      ],
      "output": {
        "type": "markdown"
      }
    }'

curl -X POST https://api.nutrient.io/build ^
  -H "Authorization: Bearer your_api_key_here" ^
  -o result.md ^
  --fail ^
  -F file=@document.pdf ^
  -F instructions="{\"parts\": [{\"file\": \"file\"}], \"output\": {\"type\": \"markdown\"}}"

package com.example.pspdfkit;

import java.io.File;
import java.io.IOException;
import java.nio.file.FileSystems;
import java.nio.file.Files;
import java.nio.file.StandardCopyOption;

import org.json.JSONArray;
import org.json.JSONObject;

import okhttp3.MediaType;
import okhttp3.MultipartBody;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public final class PspdfkitApiExample {
  public static void main(final String[] args) throws IOException {
    final RequestBody body = new MultipartBody.Builder()
      .setType(MultipartBody.FORM)
      .addFormDataPart(
        "file",
        "document.pdf",
        RequestBody.create(
          MediaType.parse("application/pdf"),
          new File("document.pdf")
        )
      )
      .addFormDataPart(
        "instructions",
        new JSONObject()
          .put("parts", new JSONArray()
            .put(new JSONObject()
              .put("file", "file")
            )
          )
          .put("output", new JSONObject()
            .put("type", "markdown")
          ).toString()
      )
      .build();

    final Request request = new Request.Builder()
      .url("https://api.nutrient.io/build")
      .method("POST", body)
      .addHeader("Authorization", "Bearer your_api_key_here")
      .build();

    final OkHttpClient client = new OkHttpClient()
      .newBuilder()
      .build();

    final Response response = client.newCall(request).execute();

    if (response.isSuccessful()) {
      Files.copy(
        response.body().byteStream(),
        FileSystems.getDefault().getPath("result.md"),
        StandardCopyOption.REPLACE_EXISTING
      );
    } else {
      // Handle the error
      throw new IOException(response.body().string());
    }
  }
}

using System;
using System.IO;
using System.Net;
using RestSharp;

namespace PspdfkitApiDemo
{
  class Program
  {
    static void Main(string[] args)
    {
      var client = new RestClient("https://api.nutrient.io/build");

      var request = new RestRequest(Method.POST)
        .AddHeader("Authorization", "Bearer your_api_key_here")
        .AddFile("file", "document.pdf")
        .AddParameter("instructions", new JsonObject
        {
          ["parts"] = new JsonArray
          {
            new JsonObject
            {
              ["file"] = "file"
            }
          },
          ["output"] = new JsonObject
          {
            ["type"] = "markdown"
          }
        }.ToString());

      request.AdvancedResponseWriter = (responseStream, response) =>
      {
        if (response.StatusCode == HttpStatusCode.OK)
        {
          using (responseStream)
          {
            using var outputFileWriter = File.OpenWrite("result.md");
            responseStream.CopyTo(outputFileWriter);
          }
        }
        else
        {
          var responseStreamReader = new StreamReader(responseStream);
          Console.Write(responseStreamReader.ReadToEnd());
        }
      };

      client.Execute(request);
    }
  }
}

// This code requires Node.js. Do not run this code directly in a web browser.

const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')

const formData = new FormData()
formData.append('instructions', JSON.stringify({
  parts: [
    {
      file: "file"
    }
  ],
  output: {
    type: "markdown"
  }
}))
formData.append('file', fs.createReadStream('document.pdf'))

;(async () => {
  try {
    const response = await axios.post('https://api.nutrient.io/build', formData, {
      headers: formData.getHeaders({
        'Authorization': 'Bearer your_api_key_here'
      }),
      responseType: "stream"
    })

    response.data.pipe(fs.createWriteStream("result.md"))
  } catch (e) {
    const errorString = await streamToString(e.response.data)
    console.log(errorString)
  }
})()

function streamToString(stream) {
  const chunks = []
  return new Promise((resolve, reject) => {
    stream.on("data", (chunk) => chunks.push(Buffer.from(chunk)))
    stream.on("error", (err) => reject(err))
    stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")))
  })
}

import requests
import json

response = requests.request(
  'POST',
  'https://api.nutrient.io/build',
  headers = {
    'Authorization': 'Bearer your_api_key_here'
  },
  files = {
    'file': open('document.pdf', 'rb')
  },
  data = {
    'instructions': json.dumps({
      'parts': [
        {
          'file': 'file'
        }
      ],
      'output': {
        'type': 'markdown'
      }
    })
  },
  stream = True
)

if response.ok:
  with open('result.md', 'wb') as fd:
    for chunk in response.iter_content(chunk_size=8096):
      fd.write(chunk)
else:
  print(response.text)
  exit()

<?php

$FileHandle = fopen('result.md', 'w+');

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.nutrient.io/build',
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_POSTFIELDS => array(
    'instructions' => '{
      "parts": [
        {
          "file": "file"
        }
      ],
      "output": {
        "type": "markdown"
      }
    }',
    'file' => new CURLFILE('document.pdf')
  ),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer your_api_key_here'
  ),
  CURLOPT_FILE => $FileHandle,
));

$response = curl_exec($curl);

curl_close($curl);

fclose($FileHandle);

POST https://api.nutrient.io/build HTTP/1.1
Content-Type: multipart/form-data; boundary=--customboundary
Authorization: Bearer your_api_key_here

--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "file"
    }
  ],
  "output": {
    "type": "markdown"
  }
}
--customboundary
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

(file data)
--customboundary--

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:

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

Shell

Run this request to convert a PDF from a URL:

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:

{
  "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:

{
  "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:

{
  "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.

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 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:

{
  "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:

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,
};

Refer to the build document endpoint API reference to convert PDFs to Markdown and combine conversion with page selection or document assembly.

Refer to the PDF-to-HTML API guide.
Refer to the Markdown-to-PDF API guide.
Refer to the PDF-to-Office API guide.
Refer to the PDF OCR API guide.
Refer to the PDF merge API guide.
Refer to the PDF split API guide.
Refer to the DWS Data Extraction API guide.
Refer to the tools and APIs guide.

PDF-to-Markdown API

Convert a PDF to Markdown

Convert a PDF from a URL

Shell

Convert selected PDF pages

Convert password-protected PDFs

Convert scanned PDFs

Compare Processor API Markdown and DWS Data Extraction API Markdown

Combine PDF-to-Markdown conversion with other processing

Reference

Was this helpful?

Help us improve

Thank you for your feedback!

Something went wrong. Please try again or let us know.

PDF-to-Markdown API

Convert a PDF to Markdown

Convert a PDF from a URL

Shell

Convert selected PDF pages

Convert password-protected PDFs

Convert scanned PDFs

Compare Processor API Markdown and DWS Data Extraction API Markdown

Combine PDF-to-Markdown conversion with other processing

Reference

Related API reference operations

Related guides

Was this helpful?

Help us improve

Thank you for your feedback!

Something went wrong. Please try again or let us know.