Document Parsing

Turn documents into text and structured data: PDF, DOCX, image OCR, CSV, and JSON parsing, markdown generation with content-filtering modes, Shadow DOM extraction, and table extraction (HTML tables and PDF tables).

What it parses

Input	What you get
PDF	Extracted text (/v1/parse) or structured tables (/v1/pdf/extract, pdfplumber default)
DOCX	Extracted text
Images	OCR'd text via Tesseract (/v1/ocr/extract from URL or base64)
CSV / JSON	Parsed content
HTML	Markdown (raw / pruned / BM25-filtered), Shadow DOM flattened content, HTML tables as records

Endpoints

Router: routers/parsing.py (tag Parsing) + routers/advanced.py (tag Advanced) + routers/extraction.py (tag Extraction)

Method	Path	Summary
POST	/v1/parse	Parse PDF/DOCX/image/CSV/JSON to text (url, timeout default 60)
POST	/v1/markdown	Generate markdown with filtering (mode = raw | fit | bm25, query, threshold)
POST	/v1/shadow-dom	Extract content from Shadow DOM (url, flatten default true)
POST	/v1/pdf/extract	Extract tables + text from a PDF (pdf_url, method default pdfplumber)
POST	/v1/ocr/extract	OCR an image (image_url or image_base64)
POST	/v1/extract-table	Extract HTML tables as structured data (url, table_index default 0)

POST /v1/parse

curl -X POST http://localhost:8005/v1/parse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"url": "https://example.com/spec.pdf", "timeout": 60}'

Response (200):

{
  "success": true,
  "data": {
    "text": "…extracted text…",
    "format": "pdf"
  }
}

POST /v1/markdown

Request body: url (required), mode (raw default | fit | bm25), query (default ""), threshold (default 0.3).

• raw — unfiltered markdown
• fit — prune boilerplate (nav, ads, footers)
• bm25 — filter by BM25 relevance to query (falls back to pruning when no query is provided)

curl -X POST http://localhost:8005/v1/markdown \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"url": "https://example.com/article", "mode": "bm25", "query": "pricing plans"}'

Response (200): { "success": true, "data": { "markdown": "…", "filter": "bm25" } }

POST /v1/shadow-dom

curl -X POST http://localhost:8005/v1/shadow-dom \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"url": "https://app.example.com", "flatten": true}'

Response (200):

{
  "success": true,
  "data": {
    "url": "https://app.example.com",
    "shadow_dom_detected": true,
    "flattened": true,
    "content": "…flattened content…",
    "raw_html_length": 48210,
    "flat_html_length": 41320
  }
}

Useful for modern web apps built with Lit, web components, or frameworks using Shadow DOM encapsulation.

POST /v1/pdf/extract

curl -X POST http://localhost:8005/v1/pdf/extract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"pdf_url": "https://example.com/report.pdf", "method": "pdfplumber"}'

Response (200):

{
  "success": true,
  "data": {
    "tables": [
      [{"Quarter": "Q1", "Revenue": 1200000}, {"Quarter": "Q2", "Revenue": 1500000}]
    ],
    "text": "…"
  }
}

POST /v1/ocr/extract

Provide image_url or image_base64:

curl -X POST http://localhost:8005/v1/ocr/extract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"image_url": "https://example.com/invoice.png"}'

Response (200):

{
  "success": true,
  "data": {
    "text": "Invoice #1042 … Total: $1,234.56",
    "source": "url"
  }
}

POST /v1/extract-table

curl -X POST http://localhost:8005/v1/extract-table \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <key>" \
  -d '{"url": "https://example.com/pricing", "table_index": 0}'

Response (200):

{
  "success": true,
  "data": {
    "table_index": 0,
    "total_tables": 2,
    "columns": ["Plan", "Price", "Seats"],
    "rows": [
      {"Plan": "Pro", "Price": "$49", "Seats": "5"},
      {"Plan": "Team", "Price": "$199", "Seats": "25"}
    ],
    "html": "<table border=\"1\" class=\"dataframe\">…</table>"
  }
}

MCP tools

Tool	Backing endpoint
pry_parse_document	POST /v1/parse (PDF/DOCX/OCR/CSV/JSON)

pry_screenshot complements document workflows by capturing rendered pages for visual QA before parsing.

Who uses this

• Data engineering — ingest PDF/CSV/JSON files into pipelines without a separate parser stack.
• RAG / LLM apps — convert PDFs and DOCX into clean text for chunking/embedding (/v1/markdown with mode=fit removes boilerplate).
• Finance/legal ops — OCR invoices, extract tables from filings (/v1/pdf/extract).
• Web scraping — shadow-dom for JS-heavy SPAs, extract-table for pricing/stat pages.

Next steps

• Extraction API — CSS/LLM/schema extraction
• Browser Automation — render-then-parse flows
• x402 Pay-per-call — pdf_extract and ocr_extract are priced operations