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

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.

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.

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.

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
  },
}

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.

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.

AbortSignal

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

ParseResult

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

string

The document content rendered as Markdown.

string

Plain text extracted from the document.

string

The document content rendered as HTML.

Array<ParsePage>

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

Array<ParsedImage>

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

Array<ParsedTable>

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

Record<string, unknown>

Document-level metadata returned by the provider.

unknown

Structured JSON output, when supported by the provider.

unknown

Chunked output, when supported by the provider.

number

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

string

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

Array<ParseWarning>

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

object

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

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