Parse endpoint

The parse endpoint extracts structured content from a document and returns either typed spatial elements with bounding boxes or a whole-document Markdown representation:

POST https://api.nutrient.io/extraction/parse

Request formats

You can send documents to the parse endpoint in three ways.

Multipart form upload

Upload a file directly with optional processing instructions.

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

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":"understand","output":{"format":"spatial"}}'
    },
)

print(response.json())

import fs from "node:fs";

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

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

When instructions is omitted, the API defaults to understand mode with spatial element output.

JSON body with URL

Process a document hosted at a public URL without uploading a file.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storage.example.com/invoice.pdf",
    "mode": "understand",
    "output": { "format": "spatial" }
  }'

import requests

response = requests.post(
    "https://api.nutrient.io/extraction/parse",
    headers={
        "Authorization": "Bearer your_api_key_goes_here",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://storage.example.com/invoice.pdf",
        "mode": "understand",
        "output": {"format": "spatial"},
    },
)

print(response.json())

const response = await fetch("https://api.nutrient.io/extraction/parse", {
  method: "POST",
  headers: {
    Authorization: "Bearer your_api_key_goes_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://storage.example.com/invoice.pdf",
    mode: "understand",
    output: { format: "spatial" },
  }),
});

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

Raw binary upload

Send a file directly as the request body with the appropriate Content-Type header.

curl -X POST https://api.nutrient.io/extraction/parse \
  -H "Authorization: Bearer your_api_key_goes_here" \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://api.nutrient.io/extraction/parse",
        headers={
            "Authorization": "Bearer your_api_key_goes_here",
            "Content-Type": "application/pdf",
        },
        data=f.read(),
    )

print(response.json())

import fs from "node:fs";

const fileBuffer = fs.readFileSync("document.pdf");

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

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

Parse cheat sheet

Use this table to avoid mixing request fields and response paths.

Request field reminders:

• Use output.format, not outputFormat, output.markdown, or a top-level markdown request field.
• configuration.outputFormat is a response field, not a request field.
• Spatial output is a flat list at output.elements[]. Page information is nested on each element at element.page, and coordinates are at element.bounds.
• Markdown output is returned at output.markdown in the JSON response.

Processing modes

The mode parameter controls the extraction pipeline.

Default: understand. Refer to the processing modes guide for a detailed comparison.

Output formats

The output.format parameter controls what the API returns.

Default format depends on the mode: text defaults to markdown; structure, understand, and agentic default to spatial.

When output.format is spatial, you can also set output.includeWords: true to include word-level OCR data nested inside paragraph and table cell elements.

Response structure

Every successful response includes:

{
  "status": 200,
  "requestId": "req_e5f6g7h8",
  "output": { ... },
  "metrics": {
    "processingTimeMs": 4200,
    "pagesProcessed": 1
  },
  "usage": {
    "data_extraction_credits": {
      "cost": 9,
      "remainingCredits": 850
    }
  },
  "configuration": {
    "mode": "understand",
    "outputFormat": "spatial"
  }
}

• requestId — Unique identifier for debugging and support requests.
• output — Contains either elements (spatial format) or markdown (Markdown format).
• metrics — Processing time and pages processed.
• usage — Credit consumption for this request.
• configuration — The mode and output format that were used.

Next steps

• Processing modes — Compare text, structure, understand, and agentic modes.
• Extract document elements — Spatial output with typed elements and bounding boxes.
• Extract Markdown — Whole-document Markdown output.
• Coordinate spaces — Understand units, bounding boxes, and how to map coordinates to rendered pages.
• Multilingual extraction — Process documents in other languages.
• Error handling — HTTP status codes and error response format.