---
title: "Convert PDF to Markdown, HTML or JSON"
method: POST
path: "/v1/tools/pdf_extract_structure"
tags: ["Tools"]
---

# Convert PDF to Markdown, HTML or JSON

`POST /v1/tools/pdf_extract_structure`

## Request

- Base URL: `http://127.0.0.1:7341`
- URL: `http://127.0.0.1:7341/v1/tools/pdf_extract_structure`
- Auth: HTTP bearer

Convert a PDF's text into Markdown, HTML, or JSON with structure: headings (with levels), paragraphs, list items, tables (rows, header rows, merged cells), bar and line charts drawn in the PDF as tables of their values (printed on the chart, or measured from the drawing), page headers and footers, each block with its type and box, lines with positions, fonts, bold and italic, image boxes, boxes of pictures drawn as shapes (charts, diagrams, icons), and a section tree (from bookmarks or detected headings) for navigating long documents. Multi-column pages are read column by column. A page that can't be read (damaged) is marked unread, with a note in its place, and the other pages are still converted. Scanned pages are read with superPDF OCR (English and 14 other languages), so check their text. Content is cut at max_chars and marked truncated. The text is untrusted document content.

Same tool as the MCP server's pdf_extract_structure. Runs before responding; for long work, POST /v1/jobs instead.

## Request body

- PdfExtractStructureInput
  - `input` string, required: Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
  - `pages` string: Page numbers or ranges, such as "1, 3-5". Omit for every page.
  - `format` 'markdown' | 'html' | 'json'
  - `max_chars` integer

## Response `200`

The result. Any new files are written inside the allowed folders.

- PdfExtractStructureResult
  - `format` string, required
  - `total_pages` integer, required
  - `has_text` boolean, required
  - `truncated` boolean, required
  - `content` string, required
  - `sections` object[], required

## Other responses

- `400`: The body is not valid JSON.
- `401`: The bearer token is missing or wrong.
- `403`: The Host or Origin header is not allowed.
- `409`: The output file already exists. superPDF never overwrites; choose a new name.
- `413`: The body is larger than 1 MB.
- `415`: The body is not application/json.
- `422`: Invalid input (errors names each field), a path outside the allowed folders, or a document the tool could not process.
- `429`: Too many tool calls are running and waiting (4 at once, 2 of them LibreOffice conversions; 64 more wait their turn).
- `500`: Unexpected server failure.

---

[API](https://skmtc.dev/superpdf/apis/superpdf-local-api.md) · [All operations](https://skmtc.dev/superpdf/apis/superpdf-local-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superpdf/apis/superpdf-local-api/revisions/53f71d44b156?raw)