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

# File Parsing

> Convert PDFs, Word documents, spreadsheets, and presentations into markdown during extraction

File parsing converts documents into clean markdown. Add `file_parsing_options` to an Extract request that points at a document URL.

<Warning>
  Enabling file parsing adds a per-page-parsed charge on top of the base Extract price. Billing is per page parsed, not per document, and depends on the mode. See [Pricing](/nimble-sdk/admin/pricing).
</Warning>

## Quick Start

### Example Request

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
  --header 'Authorization: Bearer <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "url": "https://example.com/report.pdf",
      "formats": ["markdown"],
      "file_parsing_options": {
          "mode": "pro",
          "max_pages": 50
      }
  }'
  ```
</CodeGroup>

### Example Response

```json theme={"system"}
{
  "url": "https://example.com/report.pdf",
  "task_id": "8e8cfde7-b311-42f1-8a1c-8f5b6a1c1d11",
  "status": "success",
  "data": {
    "markdown": "# Annual Report\n\n## Revenue\n\n| Quarter | Revenue |\n| --- | --- |\n| Q1 | $4.2M |\n..."
  }
}
```

## Supported file types

| Type | Extensions |
| - | - |
| PDF | `.pdf` |
| Word documents | `.docx` |
| Spreadsheets | `.xlsx`, `.xls`, `.ods`, `.csv` |
| Presentations | `.pptx`, `.ppt`, `.odp` |

Nimble detects the file type from the response `Content-Type` header, the URL file extension, or the file contents. Word documents are detected from their contents. A URL does not need to end in an extension, except for CSV files, which need a `.csv` extension or a `text/csv` content type.

## How it works

<Steps>
  <Step title="Extract downloads the file">
    Nimble fetches the document from the URL like any other Extract request.
  </Step>

  <Step title="Page limit check">
    If `max_pages` is set and a PDF has more pages, the request fails before parsing.
  </Step>

  <Step title="Parsing">
    The document is converted to markdown using the selected `mode`.
  </Step>

  <Step title="Response">
    The markdown is returned in `data.markdown`.
  </Step>
</Steps>

## Parameters

<AccordionGroup>
  <Accordion title="file_parsing_options" icon="file-pdf">
    <ParamField path="file_parsing_options" type="object">
      Enables file parsing. Omit the object to skip parsing and pay only the base Extract price.

      ```json theme={"system"}
      "file_parsing_options": {
        "mode": "pro",
        "max_pages": 50
      }
      ```
    </ParamField>

    <ParamField path="file_parsing_options.mode" default="light" type="string">
      Parsing mode.

      * `light` - Fast, text-native extraction. No OCR.
      * `pro` - Adds LLM-based parsing with OCR fallback for scanned or table-heavy PDFs. Billed at a higher per-page rate than `light`. See [Pricing](/nimble-sdk/admin/pricing).
    </ParamField>

    <ParamField path="file_parsing_options.max_pages" type="integer">
      Maximum number of pages to parse. Minimum `1`. No limit by default.

      Rejects PDFs with more pages than this limit with a `file exceeds limit` error. The PDF is not parsed and no parsing charge applies. It does not truncate. Other file types are not page-checked.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Choosing a mode

| | `light` | `pro` |
| - | - | - |
| Best for | Plain-text documents with a simple, single-column layout | Text-heavy documents with simple tables, and scanned PDFs |
| Tables | Not a focus. Best with plain text. | Simple tables preserved in markdown |
| OCR | No | Yes, as a fallback |
| Cost | Lowest per page | Higher per page |

For example, a 100-page PDF in `pro` costs \$0.75 to parse (100 pages at \$7.50 per 1,000), plus the base Extract price.

## Best practices

* **Start with `light` for digital text.** Use it for text-based documents at high volume. Switch to `pro` if tables come back flat or scanned pages come back empty.
* **Try `pro` for scans.** `light` does not run OCR, so it cannot read pages that are images of text. Test a sample before a large run.
* **Set `max_pages` when PDF sizes vary.** An unexpectedly large PDF is rejected before it is parsed. Other file types are not page-checked.
* **Request only markdown.** Set `formats` to `["markdown"]` to leave the original file out of the response.
* **Expect limited results from charts and dense visual layouts.** Neither mode is built to interpret charts, diagrams, or heavily designed pages.

## Response behavior

* When parsing succeeds, the parsed document is returned in `data.markdown`, whatever `formats` is set to.
* The original file is returned base64-encoded in `data.html` when `formats` includes `html` or when `formats` is not set. Set `formats` to `["markdown"]` to leave it out.
* If parsing fails, the request still succeeds with a warning in the response, and the failed parse is not billed. If `html` was not requested, the original file is returned in `data.html` instead of an empty response.

## Errors

| Condition | Result |
| - | - |
| PDF has more pages than `max_pages` | `400` with `file exceeds limit: <pages> pages, max_pages is <max_pages>`. No parsing charge applies. Raise `max_pages` or omit it. |

## Next steps

<CardGroup cols={2}>
  <Card title="Output Formats" icon="file-lines" href="/nimble-sdk/web-tools/extract/features/formats">
    Control which data types are returned
  </Card>

  <Card title="Pricing" icon="credit-card" href="/nimble-sdk/admin/pricing">
    Per-page rates for each mode
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.