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

# Parsing Providers: LlamaParse, Mistral OCR, and Datalab

> FileRouter supports llamaparse, mistral-ocr, and datalab, normalizing each provider's results into one consistent output contract for your application.

FileRouter connects your documents to best-in-class parsing engines without binding you to any single vendor. Each provider is wrapped in a typed adapter that handles authentication, translates FileRouter's common input format into the form the provider expects, normalizes results back into a shared contract, and surfaces errors in a consistent structure. You choose the provider at call time; FileRouter takes care of the rest.

## Supported providers

<CardGroup cols={3}>
  <Card title="LlamaParse" icon="llama">
    Rich document understanding with Markdown, page-level content, tables, images, and JSON extraction. Executes asynchronously — ideal for complex multi-page documents.
  </Card>

  <Card title="Mistral OCR" icon="eye">
    Synchronous OCR with high-confidence page data, block-level layout, tables, and images. Well-suited for scanned documents and image-heavy PDFs.
  </Card>

  <Card title="Datalab" icon="database">
    Chunked output formats (HTML, JSON, Markdown, chunks) tuned for downstream retrieval and indexing workflows. Supports multiple output formats in a single call.
  </Card>
</CardGroup>

### Provider reference

| Provider ID   | Display name | Best for                                                                          |
| ------------- | ------------ | --------------------------------------------------------------------------------- |
| `llamaparse`  | LlamaParse   | Complex PDFs, research papers, structured documents needing rich Markdown or JSON |
| `mistral-ocr` | Mistral OCR  | Scanned files, image-based PDFs, documents where confidence scoring matters       |
| `datalab`     | Datalab      | Chunked retrieval pipelines, HTML/JSON output, indexing-focused workflows         |

## What each adapter owns

Every provider adapter is a self-contained unit responsible for its own lifecycle. When you call `parse()` or `compare()`, the adapter handles:

<Steps>
  <Step title="Authentication and client construction">
    Each adapter reads its API key from the environment or from the options you pass when you configure the provider. The adapter builds and owns the native SDK client — you never interact with it directly unless you need the escape hatch (see below).
  </Step>

  <Step title="Input conversion">
    The adapter receives FileRouter's normalized input — either a validated HTTP URL or replayable bytes with a filename and MIME type — and converts it into the form the provider's API expects (a URL parameter, a multipart upload, or a binary body).
  </Step>

  <Step title="Page-number translation">
    FileRouter always uses **one-based** page numbers. Adapters translate these into whatever native representation the provider requires before making the request.
  </Step>

  <Step title="Typed provider options">
    Adapters expose their own typed options structs (see `providerOptions` below). The adapter passes these native options to the provider's API verbatim.
  </Step>

  <Step title="Normalized results and errors">
    The raw provider response is mapped into FileRouter's `ParseResult` shape. Errors from the provider are caught and re-thrown as typed `FileRouterError` instances.
  </Step>
</Steps>

## Capability enforcement

FileRouter does not assume every provider supports the same outputs. Before making any network request, FileRouter checks whether the provider you selected can produce every output you requested. If any requested output is unsupported, the call fails immediately with a clear error — no provider API call is made, and no credits are consumed.

<Warning>
  Requesting an unsupported output for a provider — for example, asking `mistral-ocr` for `chunks`, which only `datalab` supports — raises a `FileRouterError` before any I/O is attempted. Check the [Outputs](/concepts/outputs) reference to see which outputs each provider supports.
</Warning>

You can inspect configured providers and their declared capabilities at runtime:

```ts router-capabilities.ts theme={null}
import { FileRouter } from "@file_router/sdk"
import { llamaparse } from "@file_router/sdk/llamaparse"
import { mistralOcr } from "@file_router/sdk/mistral"
import { datalab } from "@file_router/sdk/datalab"

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse(),
    "mistral-ocr": mistralOcr(),
    datalab: datalab(),
  },
})

// Inspect what each configured provider can produce
const caps = router.providers
```

## Provider-specific options with `providerOptions`

Every provider exposes native options that go beyond FileRouter's common `ParseOptions`. You pass these under the `providerOptions` key, namespaced by provider ID. This namespace isolation ensures that options intended for one provider are never accidentally forwarded to another.

```ts llamaparse-agentic.ts theme={null}
import { FileRouter } from "@file_router/sdk"
import { llamaparse } from "@file_router/sdk/llamaparse"
import { mistralOcr } from "@file_router/sdk/mistral"

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse(),
    "mistral-ocr": mistralOcr(),
  },
})

const result = await router.parse("https://example.com/report.pdf", {
  provider: "llamaparse",
  outputs: ["markdown", "pages"],
  providerOptions: {
    llamaparse: {
      tier: "agentic",
      agentic_options: { custom_prompt: "Preserve footnotes" },
    },
    // These options are scoped to mistral-ocr and never reach llamaparse
    "mistral-ocr": { includeBlocks: true },
  },
})
```

<Note>
  The `providerOptions` object is keyed by provider ID. Even if you pass options for multiple providers in a single call, each adapter reads only its own namespace — cross-contamination is structurally impossible.
</Note>

## Raw client escape hatch

Each adapter optionally exposes a `raw` property that gives you direct access to the underlying native client. You can use this when you need to call a provider API feature that FileRouter does not yet surface.

```ts raw-client.ts theme={null}
import { FileRouter } from "@file_router/sdk"
import { llamaparse } from "@file_router/sdk/llamaparse"

const provider = llamaparse()

// Access the native LlamaCloud client directly, if one was constructed
const nativeClient = provider.raw
```

<Tip>
  The `raw` property is `undefined` when no client has been constructed yet (for example, before the first parse call) or when you supply a custom client object. Treat it as an optional escape hatch, not a primary interface.
</Tip>