Pass Provider-Specific Parse Options to Any Provider

FileRouter lets you pass native, provider-specific settings alongside the common parse options you already use. The providerOptions object is namespaced by provider ID — when you set providerOptions.llamaparse, only LlamaParse receives those values. Mistral OCR and Datalab never see them, and vice versa. This means you can safely configure multiple providers in a single compare call without any risk of options from one provider interfering with another.

How namespacing works

Each key in providerOptions must match a provider ID (llamaparse, mistral-ocr, or datalab). FileRouter extracts the matching namespace before forwarding the request to each provider. Providers that don’t have a matching key in providerOptions receive no extra options at all. FileRouter also applies the input source and all authentication-owned fields after any native options you supply. This means provider options cannot redirect a job to a different endpoint or override credentials — the routing is always under FileRouter’s control.

If you request a normalized output that a provider doesn’t support (for example, asking for tables from a provider that has no table capability), FileRouter fails the request before sending anything to the provider. You get an immediate error rather than a silent empty result.

Passing options to a single provider

Use providerOptions in a parse call to send typed native settings to one provider:

Parse with LlamaParse agentic options

const result = await router.parse(file, {
  outputs: ['markdown', 'images'],
  pages: [1, 3],
  provider: 'llamaparse',
  providerOptions: {
    llamaparse: {
      agentic_options: { custom_prompt: 'Preserve footnotes' },
      tier: 'agentic',
    },
  },
})

The tier and agentic_options fields map directly to LlamaParse’s official SDK request type. Page numbers are always one-based in FileRouter and are translated into each provider’s native representation automatically.

Passing different options per provider in a compare call

Because providerOptions is namespaced, you can include options for multiple providers in a single compare call. Each provider only receives its own block:

Compare with per-provider options

const result = await router.compare(file, {
  outputs: ['markdown', 'tables'],
  providerOptions: {
    llamaparse: {
      tier: 'cost_effective',
    },
    'mistral-ocr': {
      model: 'mistral-ocr-latest',
      includeImageBase64: false,
    },
  },
})

LlamaParse receives the tier field. Mistral OCR receives model and includeImageBase64. Neither provider sees the other’s options.

LlamaParse options
Mistral OCR options
Datalab options

LlamaParse options follow ParsingCreateParams from @llamaindex/llama-cloud. Protected fields (file_id, source_url, organization_id, project_id) are stripped automatically — you cannot override them through providerOptions.

LlamaParse native options reference

providerOptions: {
  llamaparse: {
    // Tier controls speed and quality trade-off
    tier: 'agentic' | 'agentic_plus' | 'cost_effective' | 'fast',
    // Pass a custom prompt for the agentic tier
    agentic_options: { custom_prompt: string },
    // Any other ParsingCreateParams fields (except protected ones)
  },
}

Mistral OCR options follow OCRRequest from @mistralai/mistralai, minus the document field (FileRouter sets that from your input). All other fields in OCRRequest are valid.

Mistral OCR native options reference

providerOptions: {
  'mistral-ocr': {
    model: 'mistral-ocr-latest',
    includeImageBase64: true,
    tableFormat: 'markdown' | 'html',
    // Any other OCRRequest fields except 'document'
  },
}

Datalab options map directly to the Convert API fields. Use the raw sub-key for any fields that FileRouter doesn’t yet expose as typed properties.

Datalab native options reference

providerOptions: {
  datalab: {
    mode: 'accurate' | 'balanced' | 'fast',
    use_llm: true,
    paginate: true,
    // Pass newly-released Datalab fields not yet typed in FileRouter
    raw: { some_new_field: 'value' },
  },
}

The `raw` escape hatch

Each configured provider exposes its underlying SDK client through provider.raw. You can use this to call provider APIs that FileRouter doesn’t currently expose as part of its normalized contract:

Access the underlying LlamaParse SDK client

import { FileRouter } from '@file_router/sdk'
import { llamaparse } from '@file_router/sdk/llamaparse'

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse({ apiKey: process.env.LLAMA_CLOUD_API_KEY }),
  },
})

// Access the native LlamaCloud client directly
const nativeClient = router.provider('llamaparse').raw

Operations performed through provider.raw bypass FileRouter’s normalization, input validation, and output selection. Use the escape hatch only for features that the FileRouter SDK doesn’t yet support natively.

Provider output capabilities

Which outputs does each provider support?

Output	LlamaParse	Mistral OCR	Datalab
`markdown`	✓	✓	✓
`text`	✓	—	—
`pages`	✓	✓	—
`tables`	✓	✓	—
`images`	✓	✓	✓
`json`	✓	✓	✓
`metadata`	✓	✓	✓
`html`	—	—	✓
`chunks`	—	—	✓

Requesting an output that a provider doesn’t support fails immediately, before any provider I/O occurs.

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

Pass Provider-Specific Parse Options to Any Provider

How namespacing works

Passing options to a single provider

Passing different options per provider in a compare call

The `raw` escape hatch

Provider output capabilities

​How namespacing works

​Passing options to a single provider

​Passing different options per provider in a compare call

​The raw escape hatch

​Provider output capabilities

How namespacing works

Passing options to a single provider

Passing different options per provider in a compare call

The `raw` escape hatch

Provider output capabilities