Extract Markdown

When output.format is set to markdown, the Data Extraction API converts the document into a Markdown string. This is useful for retrieval-augmented generation (RAG) pipelines, search indexing, and content migration workflows where structured text is more practical than spatial element data.

Basic Markdown extraction

Send a document to the extraction endpoint and request markdown output to receive the converted text.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -F "file=@document.pdf" \
  -F 'instructions={"mode":"text","output":{"format":"markdown"}}'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={"Authorization": "Bearer your_api_key_goes_here"},
    files={"file": open("document.pdf", "rb")},
    data={
        "instructions": '{"mode":"text","output":{"format":"markdown"}}'
    },
)

result = response.json()
print(result["output"]["markdown"])

import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));
form.append(
  "instructions",
  JSON.stringify({ mode: "text", output: { format: "markdown" } }),
);

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key_goes_here" },
  body: form,
});

const result = await response.json();
console.log(result.output.markdown);

Response format

The Markdown output is returned in output.markdown as a single string:

{
  "status": 200,
  "requestId": "req_a1b2c3d4",
  "output": {
    "markdown": "# Document Title\n\nFirst paragraph of text...\n\n## Section Two\n\nMore content here..."
  },
  "metrics": {
    "processingTimeMs": 312,
    "pagesProcessed": 1
  },
  "usage": {
    "data_extraction_credits": {
      "cost": 1,
      "remainingCredits": 850
    }
  },
  "configuration": {
    "mode": "text",
    "outputFormat": "markdown"
  }
}

The Markdown preserves document structure, including headings, paragraphs, lists, tables, and code blocks.

Read Markdown from the response

Use this helper when you request Markdown. It reads the standard JSON response from output.markdown and also handles a plain-text Markdown response if your integration receives one:

import json


def parse_markdown_response(response):
    content_type = response.headers.get("Content-Type", "")

    if "application/json" in content_type:
        payload = response.json()
        return payload.get("output", {}).get("markdown", "")

    if "text/plain" in content_type or "text/markdown" in content_type:
        return response.text

    # Fallback for clients or proxies that omit Content-Type.
    try:
        payload = json.loads(response.text)
    except json.JSONDecodeError:
        return response.text

    return payload.get("output", {}).get("markdown", "")