Parses an uploaded document into a rich, machine-readable Markdown representation for LLM workflows.
Supports PDF, Word, Excel, PowerPoint, email (.eml), and standalone raster images.

Conversion engine

Excel, PDF, PowerPoint, and email are converted in-process via Microsoft MarkItDown
(convert_stream). Word (.docx / .doc) uses the mammoth hybrid parser so embedded
Excel OLE workbooks in word/embeddings/ are read as tables. MarkItDown's LLM client,
Azure Document Intelligence, and OCR plugins are not used.
Embedded and standalone images are described through Agent700's phantom-agent vision pipeline
(caller JWT billing; parsingMetadata.visionApplied, warning VISION_FALLBACK_APPLIED).

Stateless transform

This endpoint performs an ephemeral in-memory transform only. Uploaded files and parsed output are
not persisted server-side. Consumers must store content, structure, and images themselves if
they need them later.

Image content

Image bytes are never returned (images[].url is always null). When embedded images are detected,
altText is populated from document metadata when available. Set use_ocr=true (or omit for auto-enable
on DOCX/PPTX/PDF with images and standalone image uploads) to populate images[].ocrText via LLM vision
extraction. Vision text is inlined in content at each image position.
When images are present and OCR is disabled, the response includes an IMAGE_CONTENT_DROPPED warning.

When to use this endpoint vs /api/helpers/parse-document

• Use rich when the LLM needs Markdown document structure, tables, emphasis, or vision-described images.
• Use simple (/api/helpers/parse-document) for quick plain-text extraction, spreadsheets/datatables
  (convertForDatatable), legacy integrations, or when JWT auth is unavailable.

Requires JWT Bearer authentication.