> ## 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.

# Parse Documents with the FileRouter SDK

> Call parse() to process a document with one provider. Choose outputs, select pages, pass provider-specific options, and read the normalized ParseResult.

`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

<ParamField body="provider" type="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.
</ParamField>

<ParamField body="outputs" type="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.
</ParamField>

<ParamField body="pages" type="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.
</ParamField>

<ParamField body="providerOptions" type="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.

  ```ts theme={null}
  providerOptions: {
    llamaparse: {
      tier: 'agentic',
      agentic_options: { custom_prompt: 'Preserve footnotes.' },
    },
    'mistral-ocr': {
      // Mistral-specific fields
    },
  }
  ```
</ParamField>

<ParamField body="includeRaw" type="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.
</ParamField>

<ParamField body="timeoutMs" type="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`.
</ParamField>

<ParamField body="signal" type="AbortSignal">
  An `AbortSignal` for cancelling the operation. Pass `AbortSignal.timeout(ms)` to enforce a custom timeout without relying on the `timeoutMs` option.
</ParamField>

## ParseResult

<ResponseField name="outputs" type="object">
  An object containing the requested output values. Only the keys you asked for in `options.outputs` are present. Common fields include:

  <Expandable title="outputs fields">
    <ResponseField name="outputs.markdown" type="string">
      The document content rendered as Markdown.
    </ResponseField>

    <ResponseField name="outputs.text" type="string">
      Plain text extracted from the document.
    </ResponseField>

    <ResponseField name="outputs.html" type="string">
      The document content rendered as HTML.
    </ResponseField>

    <ResponseField name="outputs.pages" type="Array<ParsePage>">
      Per-page breakdown. Each `ParsePage` includes `pageNumber`, optional `markdown`, `text`, `html`, `images`, `tables`, and a `warnings` array.
    </ResponseField>

    <ResponseField name="outputs.images" type="Array<ParsedImage>">
      Images extracted from the document, each with optional `url`, `data`, `mimeType`, `caption`, and `pageNumber`.
    </ResponseField>

    <ResponseField name="outputs.tables" type="Array<ParsedTable>">
      Tables extracted from the document, each with optional `markdown`, `html`, and `pageNumber`.
    </ResponseField>

    <ResponseField name="outputs.metadata" type="Record<string, unknown>">
      Document-level metadata returned by the provider.
    </ResponseField>

    <ResponseField name="outputs.json" type="unknown">
      Structured JSON output, when supported by the provider.
    </ResponseField>

    <ResponseField name="outputs.chunks" type="unknown">
      Chunked output, when supported by the provider.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="number">
  The total number of pages in the document as reported by the provider.
</ResponseField>

<ResponseField name="provider" type="string">
  The ID of the provider that processed this document (e.g. `'llamaparse'`).
</ResponseField>

<ResponseField name="warnings" type="Array<ParseWarning>">
  Non-fatal warnings from the provider. Each warning has a `code`, a `message`, and an optional `pageNumber`.
</ResponseField>

<ResponseField name="timing" type="object">
  Timing information with `startedAt`, `completedAt` (ISO 8601 strings), and `durationMs`.
</ResponseField>

<ResponseField name="raw" type="unknown">
  The complete provider response. Only present when you set `includeRaw: true` in the options.
</ResponseField>

<ResponseField name="id" type="string">
  A unique identifier for this parse result.
</ResponseField>

## 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`.

```ts parse-with-options.ts theme={null}
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)
}
```

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>