Skip to main content
POST

Overview

The Parse Document endpoint processes PDFs, images (PNG, JPEG, TIFF, WebP), presentations (PPT, PPTX), word-processing files (DOC, DOCX), and HTML files (HTML, HTM). It breaks each document into sections with text, images, tables, and optical character recognition (OCR) data. You can provide a document by direct file upload or by URL. The parse endpoint uploads your document and configuration in a single request:
  1. POST to /parse with your file and configuration: the API uploads the document and creates a parse job.
  2. The job is automatically enqueued for processing.
  3. Poll GET /parse/{job_id} to track progress and retrieve results.
Use Large File Uploads when a file is too large to send directly to POST /parse. The large-file flow returns a presigned URL for uploading the file to Unsiloed-managed storage.

Request

You must provide either file or url. If both are provided, file takes precedence.
file
Document file to process. Supported formats: PDF, images (PNG, JPEG, TIFF, WebP), presentations (PPT, PPTX), word-processing files (DOC, DOCX), and HTML files (HTML, HTM). Required if url is not provided. Use POST /parse/excel for XLS and XLSX workbooks.
string
Presigned or public URL of the document to fetch and process. Required if file is not provided.
string
Processing mode preset: fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration that trades speed for fidelity. Parameters you send explicitly take precedence over the mode. See Processing Modes to choose one. Omit to use the default configuration.
boolean
Detect and preserve strikethrough formatting in HTML and Markdown output. Defaults to false.
boolean
Detect and combine table segments across page breaks, reconstructing complete table structure by matching headers and columns. Defaults to false.
boolean
Reorder detected segments to follow the document’s natural reading order. Recommended for multi-column layouts (newspapers, two- or three-column papers) where text can otherwise interleave across columns. Defaults to false.
boolean
Run a PII detection pass before parsing. If PII is found, the task is rejected and no parsing occurs. Defaults to false.
string
JSON array string of segment types to validate and correct using a Vision Language Model, fixing misclassified segments. Example: ["Table", "Formula", "Picture"]. Defaults to ["Table", "Picture"]; an empty or unparseable value also falls back to that default, so Table and Picture validation runs even when this field is omitted.
string
Choose which types of content to include in the parsed output. Comma-separated segment types, or "all" to include everything. Defaults to "all".Available segment types:
  • table: Tabular data segments
  • picture: Image and graphic segments
  • formula: Mathematical equations
  • text: Regular text content
  • sectionheader: Section headers
  • title: Document titles
  • listitem: List items
  • caption: Image captions
  • footnote: Footnotes
  • pageheader: Page headers
  • pagefooter: Page footers
  • keyvaluepair: Key-value pairs (Agentic Lite and Agentic modes)
  • page: Full-page segments
Examples: "table", "table,picture", "table,formula", "picture,formula".
boolean
Extract and hyperlink bibliography citations in the markdown output. PDFs only. Defaults to false.
string
Digitize charts into the numbers they were drawn from. One of:
  • "basic" (default): no chart data. Picture segments keep their usual description.
  • "standard": fast and accurate chart data extraction.
  • "advanced": for the most complex and messiest charts. Contact support to have this feature enabled for your organization; until it is, a request with advanced returns 403 with error.code set to feature_not_enabled.
chart_data includes chart_type, chart_title, x_label, y_label, legend, confidence, metadata, and data: an object keyed by series name, each series a list of {"x": ..., "y": ...} points. It is attached only when the chart’s values were recovered; when it is, the segment’s markdown and html show the chart’s data as a summary and one table per series. Otherwise the segment keeps its description and has no chart_data.The Agentic (agentic) processing mode uses standard unless you set this field.
string
JSON object controlling which fields are included in the response. Set fields to false to exclude them and reduce response size. All fields default to true.Available fields:
  • html: HTML representation of segments
  • markdown: Markdown representation of segments
  • ocr: Raw OCR text data with bounding boxes and confidence scores
  • image: Cropped segment images (base64 encoded)
  • content: Text content of segments
  • bbox: Bounding box coordinates
  • confidence: Confidence scores for segments
  • embed: Vector embeddings / embed text
  • chart_data: Extracted chart data for Picture segments identified as charts
Example: {"html": true, "markdown": true, "ocr": false, "image": false}.
string
JSON object controlling HTML/Markdown generation and custom VLM prompts per segment type.Example:
Options per segment type:
  • html: "VLM" or "Auto"
  • markdown: "VLM" or "Auto"
  • vlm: Custom prompt for the VLM model. Use this to give the model specific instructions for extracting or describing these segment types.
Defaults for html and markdown are not uniform across segment types. Table.html, Picture.markdown, Formula.markdown, KeyValuePair.markdown, and both Page strategies default to "VLM"; everything else defaults to "Auto". See Segment Analysis Configuration below for the full table and override examples.
string
Specify which pages to process. Formats: "1-5", "2,4,6", "[1,3,5]". Defaults to all pages.
boolean
Transfer text color from the PDF text layer to OCR results. Defaults to false.
Attach hyperlink URLs from PDF annotations to OCR results. Defaults to false.
string
JSON array string of export formats to generate after processing, e.g. ["docx"]. When set, the pipeline generates the requested export files after parsing completes. The exported files are available as presigned URLs in the exports field of the response. Supported values: "docx", "markdown", "json".
This is a multipart form field, so the value must be a JSON-encoded string (["docx"]), not a repeated field. Passing a bare value like docx will fail to parse and silently skip the export.
string
Error handling strategy for non-critical processing errors. "Continue" (default) proceeds despite errors (e.g., LLM refusals on individual segments). "Fail" stops and fails the task on any error.
integer
Reserved field. Persisted in the task configuration but currently has no effect on retention for POST /parse — the task is not auto-deleted. To get a presigned-upload TTL, use POST /v2/parse/upload instead, where expires_in controls the upload URL’s validity.

Configuration Best Practices

Click to expand each scenario below to view detailed configuration settings, recommendations, and trade-offs for your specific use case.
Use this configuration when accuracy is critical and processing time is less important.Configuration:
When to Use:
  • Legal documents requiring precise text extraction
  • Financial statements with complex tables
  • Archival documents with low-quality scans
  • Documents where accuracy is more important than speed
Trade-offs:
  • Latency: the Agentic mode re-reads every segment, so jobs take longer
  • Latency: +1-2 seconds per page for segment validation
Use this configuration when speed is prioritized over maximum accuracy.Configuration:
When to Use:
  • High-volume document processing
  • Real-time applications requiring quick results
  • Documents with simple layouts
  • Pre-screened high-quality digital documents
Benefits:
  • Fastest processing time
  • Lower cost per document
  • Suitable for batch processing large volumes
Extract only tables and charts from financial reports and statements.Configuration:
When to Use:
  • Balance sheets and P&L statements
  • Quarterly/annual financial reports
  • Investment reports with charts
  • Documents where only structured data matters
Benefits:
  • Reduced response size (text content filtered out)
  • Focus on data-rich content
  • Merged multi-page tables for complete datasets
Extract only tabular data with minimal response size for maximum efficiency.Configuration:
When to Use:
  • Extracting data from invoices
  • Processing structured forms
  • Database population from documents
  • CSV/Excel export workflows
Benefits:
  • Minimal response payload
  • Faster data transfer
  • Easy integration with data pipelines
Extract content with structured citations from research papers and academic documents.Configuration:
When to Use:
  • Research papers with bibliographies
  • Academic articles with citations
  • Scientific documents
  • Literature reviews
Benefits:
  • Automatic citation extraction and linking
  • Structured bibliography metadata
  • In-text citation hyperlinks in markdown
  • Preserves academic document structure
Citation extraction is only available for PDF documents.
Optimize for scanned documents and images with poor text quality.Configuration:
When to Use:
  • Scanned paper documents
  • Low-quality photocopies
  • Historical documents
  • Image-based PDFs
Benefits:
  • Maximum OCR coverage
  • Better text extraction from poor quality sources
  • Higher accuracy for challenging documents
Optimize response size and performance by selectively including only the fields you need.For Minimal Response Size:
For Text-Only Processing:
For Full Analysis (Default):Omit output_fields or set all fields to True to include all available data.Benefits:
  • Reduced response size and bandwidth usage
  • Faster processing and data transfer
  • Cost optimization for high-volume processing

Parameter Details

File Input Options

The API supports two methods for providing the document to process:
  1. Direct File Upload (file parameter): Upload the document file directly as multipart/form-data
  2. Presigned URL (url parameter): Provide a publicly accessible URL or presigned URL to the document
Important Notes:
  • You must provide either file or url, but not both
  • When using url, the document will be downloaded from the provided URL before processing
  • Presigned URLs are ideal for documents already stored in cloud storage (S3, GCS, Azure Blob, etc.)
  • The URL must be publicly accessible or include necessary authentication parameters (e.g., S3 presigned URLs with signatures)
  • Supported formats are the same for both methods: PDF, images (PNG, JPEG, TIFF, WebP), presentations (PPT, PPTX), word-processing files (DOC, DOCX), and HTML files (HTML, HTM). Use POST /parse/excel for XLS and XLSX workbooks.
Use Cases for Presigned URLs:
  • Documents already stored in cloud storage
  • Avoiding duplicate file uploads
  • Integration with existing document management systems
  • Processing documents already available at a URL without uploading them again

Table Merging

The merge_tables parameter enables merging of tables that span across multiple pages: How It Works:
  • Analyzes consecutive table segments across pages
  • Identifies tables with matching column headers
  • Merges them into a single unified table structure
  • Preserves table formatting and data integrity
When to Use:
  • Multi-Page Financial Statements: Consolidate P&L statements or balance sheets spanning multiple pages
  • Large Data Tables: Merge inventory lists, transaction records, or data sets split across pages
  • Reports with Continuation Tables: Automatically combine tables marked with “continued on next page”
Example:
Benefits:
  • Simplified Data Processing: Work with complete tables instead of fragments
  • Better Context: Maintain full table context for analysis and extraction
  • Reduced Post-Processing: Eliminates need for manual table stitching

Citation Extraction (Research Papers)

This is a specialized feature for academic and research PDF documents. Not needed for general document parsing.
The xml_citation parameter enables automatic extraction and linking of citations from research papers, academic articles, and scientific documents. How It Works:
  • Extracts structured bibliography from the document
  • Identifies in-text citation references (e.g., “Chen et al., 2021”)
  • Hyperlinks citations in the markdown output to their bibliography entries
  • Returns structured citation metadata in the response
Example:
Response Metadata: When enabled, the response includes a metadata field with structured citation data:
Markdown Enhancement: In-text citations are automatically hyperlinked:
  • Original: "As shown by Chen et al. (2021)..."
  • Enhanced: "As shown by [Chen et al. (2021)](#ref-5)..."
Only available for PDF documents. This parameter is ignored for other file types (images, Office documents).

Content Type Filtering

The segment_filter parameter allows you to filter the output to include only specific segment types, reducing response size and focusing on relevant content: How It Works:
  • Accepts a comma-separated list of segment types (case-insensitive)
  • Filters segments after processing is complete
  • Removes chunks that have no segments after filtering
Available Options:
  • "all" (default): Include all segment types
  • "table": Only table segments
  • "picture": Only image/graphic segments
  • "table,picture": Tables and pictures only
  • "table,formula": Tables and formulas only
  • Custom combinations using any segment type
Supported Segment Types:
  • table, picture, formula, text, sectionheader, title, listitem, caption, footnote, pageheader, pagefooter
Example Usage:
Use Cases:
  • Tables Only: Extract only tabular data from financial documents
  • Pictures Only: Extract charts, graphs, and diagrams for visual analysis
  • Tables + Pictures: Get structured data and visualizations, skip text content
  • Custom Combinations: Mix any segment types based on your needs
Benefits:
  • Reduced Response Size: Filter out unwanted content before receiving results
  • Faster Processing: Less data to transfer and parse
  • Focused Extraction: Get only the content types you need
  • Cost Optimization: Smaller responses reduce bandwidth usage

Output Fields Configuration

The output_fields parameter allows you to control which fields are included in the API response. This is useful for reducing response size, improving performance, and optimizing bandwidth usage when you don’t need all available data. Available Fields:
  • html (default: true): Include HTML representation of segments
  • markdown (default: true): Include Markdown representation of segments
  • ocr (default: true): Include OCR results with bounding boxes and confidence scores
  • image (default: true): Include cropped segment images (base64 encoded)
  • content (default: true): Include text content of segments
  • bbox (default: true): Include bounding box coordinates
  • confidence (default: true): Include confidence scores for segments
  • embed (default: true): Include embed text in chunk responses
Usage: Set fields to false to exclude them from the response. Fields not specified default to true for backward compatibility. Example Configuration:
Benefits:
  • Reduced Response Size: Excluding large fields like image and html can significantly reduce payload size
  • Faster Processing: Less data to serialize and transfer
  • Cost Optimization: Smaller responses reduce bandwidth costs
  • Selective Data: Only retrieve the fields you need for your use case
When to Use:
  • Minimal Response: Set most fields to false when you only need basic content
  • Text-Only Processing: Exclude image and ocr when processing text content
  • Embedding Generation: Include only content and embed when generating embeddings
  • Full Analysis: Keep all fields enabled (default) for comprehensive document analysis

Segment Analysis Configuration

The segment_analysis parameter allows you to customize how different segment types are processed, including HTML/Markdown generation strategies and custom VLM prompts. Available Segment Types: You can configure processing for any of the following segment types:
  • Table: Tabular data segments
  • Picture: Image and graphic segments
  • Formula: Mathematical equations
  • Title: Document titles
  • SectionHeader: Section headers
  • Text: Regular text content
  • ListItem: List items
  • Caption: Image captions
  • Footnote: Footnotes
  • PageHeader: Page headers
  • PageFooter: Page footers
  • Page: Full page segments
  • KeyValuePair: Form field regions (labels with their filled-in values). Only produced for form documents; the config is accepted either way.
Configuration Options: For each segment type, you can specify:
  • html: Generation strategy for HTML representation
    • "Auto": Build HTML directly from the OCR/recognized text (skips the VLM call — faster and cheaper)
    • "VLM": Use a VLM to generate HTML
  • markdown: Generation strategy for Markdown representation
    • "Auto": Build Markdown directly from the OCR/recognized text (skips the VLM call — faster and cheaper)
    • "VLM": Use a VLM to generate Markdown
    Defaults are not uniform across segment types. Four cases use VLM by default so the output is usable without extra configuration:If you want a Picture segment’s Markdown to contain only the transcribed text (rather than a VLM-written description), pass segment_analysis={"Picture": {"markdown": "Auto"}}. The same override applies to Table.html and Formula.markdown. Auto is faster and cheaper, but loses VLM summarization for image-heavy segments.
    KeyValuePair keeps each label with its value in one segment, checkbox and radio state included. It also carries an image crop URL when you poll with include_url=true.
  • vlm: Custom prompt for the VLM model. Use this to give the model specific instructions for extracting or describing these segment types.
Example Configuration:
Use Cases:
  • VLM-Enhanced Output: Use "VLM" for both html and markdown generation strategies to get AI-enhanced representations in those fields
  • Custom Instructions: Use vlm to tell the model how to read a segment type, for example how to treat merged cells in tables

Response

string
required
Job identifier. Pass this to GET /parse/{job_id} to poll for results.
string
required
Initial job status. Always "Starting" on creation.
string
required
Name of the uploaded file. For URL submissions this is the last path segment of the URL, or "unknown" when no usable segment exists.
string
required
ISO 8601 timestamp when the job was created.
string
required
Human-readable status message with a polling hint.
integer
required
Number of pages deducted from your quota for this job.
integer
required
Remaining page quota after this job was deducted.
boolean
required
Whether table merging is enabled for this job (reflects the submitted merge_tables value).

Document Analysis Features

The parsing endpoint provides comprehensive document analysis including:

Text Extraction

Extracts text content with high accuracy, preserving formatting and structure.

Image Recognition

Identifies and analyzes images within documents, providing descriptions and metadata.

Table Parsing

Extracts tabular data with proper structure and formatting.

OCR Processing

Performs optical character recognition on text elements with confidence scores.

Section Detection

Automatically identifies different document sections like headers, body text, and captions.

Bounding Box Information

Provides precise coordinates for all extracted elements.

Advanced Content Processing

  • VLM-Enhanced Analysis: Uses vision-language models for better content understanding
  • Multi-Format Output: Generates HTML, Markdown, and plain text versions
  • Context-Aware Processing: Maintains document context across segments
  • Intelligent Chunking: Creates semantically meaningful document chunks

Retrieving Results

After the job is created, use the GET /parse/ endpoint to check status and retrieve results:
cURL
Python

Expected Results Structure

When the job completes successfully, the response contains comprehensive document analysis with enhanced processing:

Segment Types

The parsing API identifies and processes different types of document segments with enhanced processing:

Picture

Images and graphics within the document, including logos, charts, and illustrations. Enhanced with VLM-based description generation.

SectionHeader

Document headers and titles that define section boundaries. Processed with semantic understanding.

Text

Regular text content including paragraphs, sentences, and individual text elements. Enhanced with context-aware processing.

Table

Tabular data with structured rows and columns. Enhanced with VLM-based formatting. The table reader is chosen by the processing mode; use vlm in the segment_analysis parameter to give it custom instructions.

Caption

Text captions associated with images or figures. Processed with relationship awareness.

Formula

Mathematical equations and expressions. Enhanced with specialized formula processing.

Title

Document titles and main headings. Processed with enhanced formatting.

Footnote

Document footnotes and references. Processed with context linking.

ListItem

Bulleted and numbered list items. Processed with structure preservation.

KeyValuePair

Form field regions — a printed label together with the value filled in against it. Produced for form documents in the Agentic Lite and Agentic modes (mode=agentic_lite or mode=agentic). See Element Types for a full response sample. Each segment includes detailed metadata such as confidence scores, bounding boxes, OCR data, and formatted output in both HTML and Markdown with VLM enhancement.

Error Handling

Common Error Scenarios

  1. Invalid API Key: Authentication failed
  2. File Too Large: File exceeds size limits
  3. Invalid Configuration: Malformed processing parameters
  4. Server Error: Internal processing error
  5. Processing Timeout: Task took too long to complete
  6. Missing File or URL: Neither file nor url parameter provided
  7. Both File and URL Provided: Cannot provide both file and url simultaneously
  8. Invalid URL: URL is not accessible or malformed
  9. URL Download Failed: Unable to download document from provided URL
  10. Insufficient Quota (402): Not enough page credits remaining.
  11. Usage Limit Exceeded (429): Billing usage cap reached. Returns plain text: Usage limit exceeded. No Retry-After header.
  12. Rate Limit Exceeded (429): Org exceeded its per-second request budget (100 requests per second per organization by default; higher limits are available on request). Returns JSON {"error": "rate_limit_exceeded", "message": ..., "retry_after": 1} with a Retry-After: 1 header.
  13. Internal Server Error (500): An unexpected error occurred during processing.
  14. Service Unavailable (503): Job queue is at capacity. Retry after the duration indicated in the Retry-After header.
  15. Forbidden (403): Access has been revoked.

Authorizations

api-key
string
header
required

API key for authentication. Send it in the api-key request header.

Body

Multipart form data. Provide either file (binary upload) or url (presigned/public URL), not both.

Request body for POST /parse (multipart/form-data).

Provide either file (binary upload) or url (presigned/public URL) — not both.

enhance_reading_order
boolean | null
default:false

Reorder detected segments to follow the document's natural reading order. Useful for multi-column layouts (newspapers, two- or three-column papers). Defaults to false.

error_handling
string | null
default:Continue

Error handling strategy for non-critical processing errors. Continue (default) — proceed despite errors (e.g., LLM refusals). Fail — stop and fail the task on any error.

expires_in
integer<int32> | null

Seconds until the task and its output are deleted. Defaults to the plan expiration time.

export_format
enum<string>[] | null

Export format(s) to generate after processing. When set, the pipeline generates the requested export files after parsing completes. The exported files are available as presigned URLs in the exports field of the response. Supported: ["docx", "markdown", "json"].

Available options:
docx,
markdown,
json
Example:
extract_colors
boolean | null
default:false

Transfer text color from the PDF text layer to OCR results. Defaults to false.

Attach hyperlink URLs from PDF annotations to OCR results. Defaults to false.

extract_strikethrough
boolean | null
default:false

Preserve strikethrough formatting in HTML/Markdown output. Defaults to false.

file
file

Document file to process. Required if url is not provided. Supported formats: PDF, PNG, JPEG, TIFF, WebP, PPT, PPTX, DOC, DOCX, XLS, XLSX, HTML, HTM.

merge_tables
boolean | null
default:false

Merge tables that span multiple pages into a single unified structure. Defaults to false.

output_fields
string | null

JSON object controlling which output fields are included in the response. Example: {"html": false, "markdown": true, "ocr": false}. All fields default to true.

page_range
string | null

Page range to process. Formats: "1-5", "2,4,6", "[1,3,5]". Defaults to all pages.

segment_analysis
string | null

JSON object controlling HTML/Markdown generation and custom VLM prompts per segment type. Example: {"Table": {"html": "VLM", "vlm": "Preserve merged cells."}}.

segment_filter
string | null
default:all

Content filter: comma-separated segment types to keep. Example: "table,picture". Use "all" to include everything. Defaults to "all".

url
string | null

Presigned or public URL of the document to fetch and process. Required if file is not provided.

validate_segments
string | null

JSON array string of segment types to validate with VLM. Example: ["Table", "Formula", "Picture"]. Defaults to ["Table", "Picture"]; an empty or unparseable value also falls back to that default.

xml_citation
boolean | null
default:false

Extract and hyperlink bibliography citations in the markdown output. PDFs only. Defaults to false.

extract_charts
enum<string> | null
default:basic

Digitize charts into the numbers they were drawn from, attached to the Picture segment as chart_data. basic (default): no chart data. standard: fast and accurate chart data extraction. advanced: for the most complex and messiest charts; contact support to have it enabled for your organization (otherwise 403 with error.code = feature_not_enabled).

Available options:
basic,
standard,
advanced
detect_pii
boolean | null
default:false

Run a PII detection pass before parsing. If PII is found, the task is rejected and no parsing occurs. Defaults to false.

mode
enum<string> | null

Processing mode preset. fast (Fast), agentic_lite (Agentic Lite), or agentic (Agentic). Each mode applies a recommended processing configuration; see Processing Modes. Parameters you send explicitly take precedence over the mode. Omit to use the default configuration.

Available options:
fast,
agentic_lite,
agentic

Response

Job created — poll with GET /parse/{job_id} to retrieve results.

Response body for a successful POST /parse call.

created_at
string
required

ISO 8601 timestamp when the job was created.

credit_used
integer<int32>
required

Number of pages deducted from your quota for this job.

file_name
string
required

Name of the uploaded file or "unknown" when a URL was provided.

job_id
string
required

Job identifier — pass this to GET /parse/{job_id} to poll for results.

merge_tables
boolean
required

Whether table merging is enabled for this job (reflects the submitted merge_tables value).

message
string
required

Human-readable status message with a polling hint.

quota_remaining
integer<int64>
required

Remaining page quota after this job was deducted.

status
string
required

Initial job status. Always "Starting" on creation.