> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Customize parsing behavior and choose which output fields the **Parse** returns.

Use configuration options when the default output is not enough for your workflow. Enable options based on the document characteristics and the output your application requires.

<Note>
  Enabling every option does not necessarily improve the result. Some options increase response size or processing time.
</Note>

## Configuration object

```json theme={null}
{
  "document": {
    "password": "pdf-password"
  },
  "capabilities": {
    "include_hierarchy": true,
    "include_table_structure": true,
    "pages": false,
    "title_tree": false
  },
  "scope": {
    "page_range": "1-10"
  },
  "config": {
    "force_engine": "textin"
  }
}
```

| Section        | Purpose                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| `document`     | Document-specific settings, such as a PDF password                      |
| `capabilities` | Controls the output fields and parsing capabilities returned by the API |
| `scope`        | Limits parsing to selected pages                                        |
| `config`       | Advanced configuration                                                  |

## Common configurations

<Tabs>
  <Tab title="RAG and search">
    Use this configuration when you need structure-aware chunks, headings, and table content.

    ```json theme={null}
    {
      "capabilities": {
        "include_hierarchy": true,
        "title_tree": true
      }
    }
    ```

    This returns:

    * Heading and section relationships
    * A document title tree
    * Structured table data
  </Tab>

  <Tab title="Complex tables">
    Use this configuration when tables need to be processed programmatically.

    ```json theme={null}
    {
      "capabilities": {
        "include_table_structure": true,
        "table_view": "html"
      }
    }
    ```

    This returns row, column, cell, span, and coordinate information for table elements when available.
  </Tab>

  <Tab title="Scanned or photographed pages">
    Use preprocessing options only when the document needs them.

    ```json theme={null}
    {
      "capabilities": {
        "crop_dewarp": true
      }
    }
    ```

    Enable:

    * `crop_dewarp` when pages are rotated, curved, cropped unevenly, or photographed at an angle.
    * `remove_watermark` only when visible watermarks interfere with recognition.
    * `include_char_details` only when character-level information or confidence scores are required.
  </Tab>
</Tabs>

## Capabilities

### `include_hierarchy`

Return parent-child relationships between elements.

| Field               | Type    | Default |
| ------------------- | ------- | ------- |
| `include_hierarchy` | boolean | `true`  |

When enabled, elements may include relationship metadata such as parent and child element identifiers.

Use for:

* RAG chunking with context preservation
* Document navigation
* Hierarchical content analysis

### `include_table_structure`

Return detailed table structure with rows, columns, cells, spans, and cell coordinates.

| Field                     | Type    | Default |
| ------------------------- | ------- | ------- |
| `include_table_structure` | boolean | `false` |

Use for:

* Programmatic table processing
* Financial report analysis
* Database imports
* Extracting specific cells

### `include_inline_objects`

Return formulas, handwriting, checkboxes, and inline images within text when detected.

| Field                    | Type    | Default |
| ------------------------ | ------- | ------- |
| `include_inline_objects` | boolean | `false` |

Use for:

* Scientific papers
* Mathematical documents
* Forms with checkboxes
* Mixed-content documents

### `include_image_data`

Return image URLs or image data for Image elements.

| Field                | Type    | Default |
| -------------------- | ------- | ------- |
| `include_image_data` | boolean | `false` |

Use for:

* Downloading images from documents
* Image processing pipelines
* Visual content extraction

### `include_char_details`

Return character-level coordinates and confidence scores when available.

| Field                  | Type    | Default |
| ---------------------- | ------- | ------- |
| `include_char_details` | boolean | `false` |

<Warning>
  Use this only when you need character-level information. It can significantly increase response size.
</Warning>

### `pages`

Return page-level metadata.

| Field   | Type    | Default |
| ------- | ------- | ------- |
| `pages` | boolean | `false` |

Page metadata can include page dimensions, rotation, and element references.

### `title_tree`

Return a document outline based on detected headings.

| Field        | Type    | Default |
| ------------ | ------- | ------- |
| `title_tree` | boolean | `false` |

Use for:

* Table of contents generation
* Section-aware navigation
* Structure-aware chunking

### `table_view`

Choose the text representation for table elements.

| Field        | Type   | Values             |
| ------------ | ------ | ------------------ |
| `table_view` | string | `markdown`, `html` |

Use `html` when complex tables cannot be represented clearly in Markdown.

### `remove_watermark`

Attempt to remove visible watermarks before recognition.

| Field              | Type    | Default |
| ------------------ | ------- | ------- |
| `remove_watermark` | boolean | `false` |

Enable this only when watermarks interfere with text recognition.

### `crop_dewarp`

Correct skewed, curved, or photographed pages before recognition.

| Field         | Type    | Default |
| ------------- | ------- | ------- |
| `crop_dewarp` | boolean | `false` |

Enable this when pages are rotated, curved, cropped unevenly, or photographed at an angle.

## Scope

### `page_range`

Parse only selected pages.

```json theme={null}
{
  "scope": {
    "page_range": "1-5,10,15-20"
  }
}
```

Use `page_range` to:

* Test parsing on a subset of pages
* Reduce processing time
* Split a document that exceeds page limits
* Process only the pages your application needs

## Document settings

### `password`

Pass the password for a password-protected PDF.

```json theme={null}
{
  "document": {
    "password": "pdf-password"
  }
}
```

## Advanced configuration

### `force_engine`

Force a specific parsing engine when supported.

```json theme={null}
{
  "config": {
    "force_engine": "textin"
  }
}
```

<Warning>
  Only use advanced engine settings when instructed by TextIn support or when your application requires a specific engine behavior.
</Warning>

### `engine_params`

Pass engine-specific parameters.

```json theme={null}
{
  "config": {
    "engine_params": {
      "parse_mode": "auto",
      "formula_level": 0,
      "image_output_type": "url",
      "recognize_chemical": false
    }
  }
}
```

| Parameter            | Type    | Values                         | Description                                                                                                                                                                                                                                                                                                 |
| -------------------- | ------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parse_mode`         | string  | `auto`, `scan`, `parse`, `vlm` | How the PDF is parsed. <ul><li>`auto`: The engine selects the mode automatically. Works for the widest range of documents.</li><li>`scan`: Treat every page as an image.</li><li>`parse`: Extract text from digital PDFs only. Fastest option.</li><li>`vlm`: Parse with a vision-language model.</li></ul> |
| `formula_level`      | int     | `0`, `1`                       | Formula recognition level: `0` for standard, `1` for enhanced.                                                                                                                                                                                                                                              |
| `image_output_type`  | string  | `url`, `base64`                | How images are returned, as a `url` or `base64` string.                                                                                                                                                                                                                                                     |
| `recognize_chemical` | boolean | `true`, `false`                | Extract chemical molecular structures from the document. Takes effect only in `vlm` mode. When enabled, the results appear in each element's `text` field.                                                                                                                                                  |

<Note>
  Engine parameters may change across engines and versions. Use them only when you have a documented requirement.
</Note>

## Performance tips

* Use the default configuration for the first integration.
* Enable table structure only when you need cell-level table data.
* Enable character details only when you need character-level coordinates or confidence scores.
* Use `page_range` to test large documents before parsing the full file.
* Use the asynchronous API for large documents, batch processing, or workflows that do not need the result in the original request.

Synchronous requests and asynchronous jobs both have a maximum processing time of 10 minutes. See [Supported Files & Limits](/xparse/supported-files) for current limits.

## Related resources

<CardGroup cols={2}>
  <Card title="Parse Quickstart" icon="rocket" href="/xparse/parse/quickstart">
    Parse your first document.
  </Card>

  <Card title="Response Format" icon="code" href="/xparse/parse/response-format">
    Understand the response structure.
  </Card>

  <Card title="Async Processing" icon="clock" href="/xparse/parse/async-processing">
    Process large documents asynchronously.
  </Card>

  <Card title="Supported Files & Limits" icon="file" href="/xparse/supported-files">
    Review supported formats and limits.
  </Card>
</CardGroup>