Parse Documents with the FileRouter SDK

router.parse(input, options) is the core operation in FileRouter. You pass a document input and an options object specifying which provider to use and what outputs you want, and the method returns a normalized ParseResult. Both FileRouter (BYOK) and FileRouterClient (hosted) expose the same parse() signature, so you can switch between modes without rewriting your parsing logic.

Accepted inputs

You can pass a document as any of the following types:

A URL string or URL object (e.g. 'https://example.com/report.pdf')
A local file path string (e.g. './report.pdf')
A File or Blob instance
An ArrayBuffer or typed array view (Uint8Array, etc.)
A ReadableStream<Uint8Array>
An explicit object: { kind: 'bytes', data, name?, mimeType? } or { kind: 'url', url }

ParseOptions

provider

string

The ID of the provider to use for this parse operation (e.g. 'llamaparse', 'mistral-ocr', 'datalab'). If omitted, the router uses the first configured provider.

outputs

Array<string>

default:"['markdown']"

The output types you want in the result. Available values are: 'chunks', 'html', 'images', 'json', 'markdown', 'metadata', 'pages', 'tables', 'text'. The router validates that the selected provider supports every requested output before sending the file — unsupported outputs fail immediately with a ProviderUnsupportedOutput error.

pages

Array<number>

A subset of one-based page numbers to process (e.g. [1, 3, 5]). The router translates these into each provider’s native page representation. When omitted, all pages are processed.

providerOptions

ProviderParseOptions

Namespaced provider-specific options. Each key matches a provider ID, and only the relevant provider’s options are forwarded. This means provider-specific settings never bleed into other providers during a compare run.

providerOptions: {
  llamaparse: {
    tier: 'agentic',
    agentic_options: { custom_prompt: 'Preserve footnotes.' },
  },
  'mistral-ocr': {
    // Mistral-specific fields
  },
}

includeRaw

boolean

default:"false"

Set to true to include the complete provider response in result.raw. This can substantially increase result size — use it only when you need access to provider-native fields that aren’t surfaced in the normalized outputs.

timeoutMs

number

default:"600000"

Maximum time in milliseconds to wait for the job to complete. Defaults to 10 minutes (600 000 ms). If the job doesn’t complete in time, the SDK throws a FileRouterError with code Timeout.

signal

AbortSignal

An AbortSignal for cancelling the operation. Pass AbortSignal.timeout(ms) to enforce a custom timeout without relying on the timeoutMs option.

ParseResult

outputs

object

An object containing the requested output values. Only the keys you asked for in options.outputs are present. Common fields include:

Show outputs fields

outputs.markdown

string

The document content rendered as Markdown.

outputs.text

string

Plain text extracted from the document.

outputs.html

string

The document content rendered as HTML.

outputs.pages

Array<ParsePage>

Per-page breakdown. Each ParsePage includes pageNumber, optional markdown, text, html, images, tables, and a warnings array.

outputs.images

Array<ParsedImage>

Images extracted from the document, each with optional url, data, mimeType, caption, and pageNumber.

outputs.tables

Array<ParsedTable>

Tables extracted from the document, each with optional markdown, html, and pageNumber.

outputs.metadata

Record<string, unknown>

Document-level metadata returned by the provider.

outputs.json

unknown

Structured JSON output, when supported by the provider.

outputs.chunks

unknown

Chunked output, when supported by the provider.

pageCount

number

The total number of pages in the document as reported by the provider.

provider

string

The ID of the provider that processed this document (e.g. 'llamaparse').

warnings

Array<ParseWarning>

Non-fatal warnings from the provider. Each warning has a code, a message, and an optional pageNumber.

timing

object

Timing information with startedAt, completedAt (ISO 8601 strings), and durationMs.

raw

unknown

The complete provider response. Only present when you set includeRaw: true in the options.

string

A unique identifier for this parse result.

Complete example

The example below parses a PDF from a URL using LlamaParse, requests both Markdown and per-page output, and passes a custom prompt through providerOptions.

parse-with-options.ts

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

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse(),
  },
})

const result = await router.parse('https://example.com/annual-report.pdf', {
  provider: 'llamaparse',
  outputs: ['markdown', 'pages'],
  pages: [1, 2, 3],
  providerOptions: {
    llamaparse: {
      tier: 'agentic',
      agentic_options: {
        custom_prompt: 'Preserve all footnotes and table formatting.',
      },
    },
  },
})

// Access normalized outputs
console.log(result.outputs.markdown)
console.log(`Parsed ${result.pageCount} page(s) with ${result.provider}`)

// Inspect per-page content
for (const page of result.outputs.pages ?? []) {
  console.log(`Page ${page.pageNumber}:`, page.markdown)
}

// Check for warnings
if (result.warnings.length > 0) {
  console.warn('Parse warnings:', result.warnings)
}

Page numbers are always one-based throughout FileRouter. If you pass pages: [1, 3], you get the first and third pages of the document. The router translates these into each provider’s native representation automatically.

Keep includeRaw disabled in production unless you specifically need the raw provider response. Provider-native JSON payloads can be large, particularly for image-heavy documents.

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

Parse Documents with the FileRouter SDK

Accepted inputs

ParseOptions

ParseResult

Complete example

​Accepted inputs

​ParseOptions

​ParseResult

​Complete example

Accepted inputs

ParseOptions

ParseResult

Complete example