Configuration Options

The Parse API accepts a config object that controls how documents are parsed and processed. Configuration options are organized into several categories:

• Target Format: Output format for parsed content (markdown vs spatial)
• Chunking Strategy: How the document is divided into chunks
• Block Options: Fine-grained control over parsing specific layout types
• Advanced Options: OCR enhancements and page filtering

For more information on default values and the full schema, see the Create Parse Run API reference.

Prefer a UI? Extend Studio lets you configure the parser visually and export the config JSON.

Target format

target

Type: "markdown" | "spatial"

Determines how content is extracted and formatted from the document.

• markdown: Clean, logical reading order using true markdown constructs (headings, lists, tables, checkboxes). Supports section-aware chunking and works best for LLMs and RAG.
• spatial: Layout/position-preserving text that uses markdown elements for block types (e.g. tables, checkboxes) but is not strictly markdown due to tabs/whitespace used to preserve relative spatial placement. Chunks are page-based only.

When to choose markdown:

• Default choice for most documents
• Better for multi-column layouts (content is linearized into readable paragraphs)
• Enables logical section chunking for improved retrieval
• Ideal for getting chunks to embed in RAG pipelines

When to choose spatial:

• Very messy, scanned, or handwritten docs (e.g. healthcare notes, skewed scans) where even the best reading order models fail to correctly parse the document
• You need a near 1:1 representation of the original layout
• For data extraction use cases, especially on scanned/skewed documents, this target can often perform better by reducing chance of improper reading order messing up logical interpretation of the document in an extraction pipeline

Tip: If unsure, prefer markdown. Only consider spatial in special cases

1
{
2
  "config": {
3
    "target": "markdown"
4
  }
5
}

Chunking strategy

chunkingStrategy.type

Type: "page" | "section" | "document"

Determines the granularity of document chunking.

"page" — Creates a separate chunk for each page of the document. Compatible with both markdown and spatial targets.

"section" — Chunks the document into logical sections based on markdown structure (headings, subheadings). The parser ensures logical groups of content are preserved by never breaking markdown elements across chunks. Only works with target: "markdown". This is ideal for RAG systems where each chunk should be a complete semantic unit.

"document" — Treats the entire document as a single chunk. Use this for small documents or when you have custom downstream chunking requirements.

1
{
2
  "config": {
3
    "chunkingStrategy": {
4
      "type": "section"
5
    }
6
  }
7
}

chunkingStrategy.options.minCharacters

Type: number

The minimum number of characters per chunk. Small sections may be combined to meet this minimum.

chunkingStrategy.options.maxCharacters

Type: number

The maximum number of characters per chunk. Long sections will be split at natural boundaries when possible.

1
{
2
  "config": {
3
    "chunkingStrategy": {
4
      "type": "section",
5
      "options": {
6
        "minCharacters": 500,
7
        "maxCharacters": 2000
8
      }
9
    }
10
  }
11
}

Block options

Fine-grained control over how specific content types are detected and formatted.

Figures

blockOptions.figures.enabled

Type: boolean

Enables or disables figure detection and parsing. When enabled, the visual languages models will do additional processing, classification and summarization of images, charts, diagrams, and more to analyze and extract content from each figure.
Note: This adds processing latency, especially for documents with many figures. Disable for fastest processing.

blockOptions.figures.figureImageClippingEnabled

Type: boolean

When enabled, extracts figure images from the document and uploads them to blob storage, providing presigned URLs in the output. Each figure is cropped from the page and saved as a PNG.

1
{
2
  "config": {
3
    "blockOptions": {
4
      "figures": {
5
        "enabled": true,
6
        "figureImageClippingEnabled": true
7
      }
8
    }
9
  }
10
}

Tables

blockOptions.tables.targetFormat

Type: "markdown" | "html"

Controls the output format for tables.

• markdown: Human-readable pipe syntax, works well with LLMs
• html: Preserves complex table structure (merged cells, rowspan, colspan)

blockOptions.tables.tableHeaderContinuationEnabled

Type: boolean

When enabled, automatically propagates table headers across page breaks. Useful for long tables spanning multiple pages where headers are only present on the first page.

1
{
2
  "config": {
3
    "blockOptions": {
4
      "tables": {
5
        "targetFormat": "html",
6
        "tableHeaderContinuationEnabled": true
7
      }
8
    }
9
  }
10
}

Text

blockOptions.text.signatureDetectionEnabled

Type: boolean

Enables advanced signature detection. When enabled, identifies handwritten signatures, initials, and signature blocks in the document.

blockOptions.text.agentic.enabled

Type: boolean

Enables OCR corrections using vision language models to review and correct low OCR confidence and difficult to parse handwriting. The system automatically identifies text regions with low OCR confidence and applies VLM-based corrections.

When to enable:

• Handwritten documents or forms
• Poor quality scans
• Historical documents or faded text
• Mixed print and handwritten content

Note: Increases latency, especially when every page is scanned.

1
{
2
  "config": {
3
    "blockOptions": {
4
      "text": {
5
        "signatureDetectionEnabled": true,
6
        "agentic": {
7
          "enabled": true
8
        }
9
      }
10
    }
11
  }
12
}

Advanced options

advancedOptions.pageRotationEnabled

Type: boolean

Enables automatic page rotation detection and correction. The system detects if pages are rotated and automatically rotates them to the correct orientation before parsing.

1
{
2
  "config": {
3
    "advancedOptions": {
4
      "pageRotationEnabled": true
5
    }
6
  }
7
}

advancedOptions.pageRanges

Type: Array<{ start: number, end: number }>

Specifies which pages of the document to process. Page numbers are 1-based and ranges are inclusive. Ranges can overlap and be in any order—the system automatically merges and sorts them.

1
{
2
  "config": {
3
    "advancedOptions": {
4
      "pageRanges": [
5
        { "start": 1, "end": 3 },
6
        { "start": 10, "end": 10 }
7
      ]
8
    }
9
  }
10
}

• 1-based, inclusive page numbers
• Ranges can overlap or arrive out of order; the platform merges and sorts them automatically
• Omit the field or pass [] to process the full document (subject to global limits)
• You are only billed for pages actually processed

Excel

advancedOptions.excelParsingMode

Type: "basic" | "advanced"

Controls how Excel files are parsed.

• basic: Fast, deterministic parsing.
• advanced: Enable layout block detection for complex spreadsheets.

For .xls files, basic mode is always used.

1
{
2
  "config": {
3
    "advancedOptions": {
4
      "excelParsingMode": "advanced"
5
    }
6
  }
7
}

advancedOptions.excelSkipHiddenContent

Type: boolean

When enabled, hidden rows, columns, and sheets are excluded from parsed Excel output.

1
{
2
  "config": {
3
    "advancedOptions": {
4
      "excelSkipHiddenContent": true
5
    }
6
  }
7
}

advancedOptions.returnOcr

Options for returning raw OCR data in the response.

advancedOptions.returnOcr.words

Type: boolean

When enabled, returns word-level bounding boxes in the response under output.ocr.words. Each word includes content, boundingBox, confidence (0-1), and pageNumber. Coordinates are in points (1/72 inch) from the top-left corner.

Useful for building document viewers with precise text selection, word-level search highlighting, or OCR quality assessment.

Note: This meaningfully impacts the response size. Consider using the signed URL return format (responseType=url) for large documents.

1
{
2
  "config": {
3
    "advancedOptions": {
4
      "returnOcr": {
5
        "words": true
6
      }
7
    }
8
  }
9
}

Response structure:

1
{
2
  "object": "parse_run",
3
  "output": {
4
    "chunks": [...],
5
    "ocr": {
6
      "words": [
7
        {
8
          "content": "Invoice",
9
          "boundingBox": {
10
            "left": 72.5,
11
            "top": 50.2,
12
            "right": 120.3,
13
            "bottom": 65.8
14
          },
15
          "confidence": 0.99,
16
          "pageNumber": 1
17
        }
18
      ]
19
    }
20
  }
21
}

Response type

You can specify the response type in the responseType query parameter for the Create Parse Run and Get Parse Run endpoints.

• json returns parsed outputs directly in the response body.
• url returns a presigned URL to the parsed content in outputUrl.

Use url for large documents to reduce response payload size, especially when returnOcr.words is enabled.