FileRouterClient: Connect to the Hosted Service

FileRouterClient is the class you use to interact with the hosted FileRouter service. It manages authentication, submits parse and compare jobs to the FileRouter API, and polls for results automatically — you just await the call. The hosted service handles job durability, so transient failures don’t require you to resubmit.

Constructor

Import FileRouterClient from @file_router/sdk and call new FileRouterClient(). Without any arguments, the client reads FILEROUTER_API_KEY from your environment.

client.ts

import { FileRouterClient } from '@file_router/sdk'

// Reads FILEROUTER_API_KEY from the environment automatically
const client = new FileRouterClient()

// Or pass the key explicitly
const clientWithKey = new FileRouterClient({
  apiKey: 'fr_live_your_key_here',
})

Constructor options

apiKey

string

Your FileRouter API key. If omitted, the client reads FILEROUTER_API_KEY from the environment. The constructor throws a FileRouterError with code Auth if no key is found.

baseURL

string

default:"https://filerouter.dev"

Override the FileRouter API base URL. Useful for pointing at a staging environment. The client also reads FILEROUTER_API_URL from the environment as a fallback before using the default.

fetch

typeof globalThis.fetch

Provide a custom fetch implementation. Useful in environments where the global fetch is unavailable or you need request interception for testing.

pollingIntervalMs

number

default:"1000"

How often the client polls for job completion, in milliseconds. Increase this value if you want to reduce API traffic for long-running jobs.

Methods

FileRouterClient exposes two core methods that mirror the BYOK FileRouter interface exactly. This means you can switch between hosted and BYOK modes without changing your parsing logic.

parse()

Process a single document with one provider. Returns a ParseResult with normalized outputs, page count, and optional raw provider response.

compare()

Run one document through multiple providers concurrently. Returns a CompareResult with a providers array containing each provider’s outcome.

Idempotency keys

Both parse() and compare() on the hosted client accept an idempotencyKey option. The client generates a random UUID for every call by default, so retrying on a network failure is safe. Pass an explicit idempotencyKey when you want to guarantee that re-submitting the same logical job — for example, after a process crash — returns the existing result rather than creating a new job.

idempotencyKey

string

An explicit idempotency key for this request. When you retry with the same key, the hosted service returns the result of the original job. If omitted, the client generates a new UUID automatically.

Complete example

The example below sends a PDF by URL to the hosted service, requests markdown and per-page output from the llamaparse provider, and prints the result.

parse-example.ts

import { FileRouterClient } from '@file_router/sdk'

const client = new FileRouterClient()

const result = await client.parse('https://example.com/report.pdf', {
  provider: 'llamaparse',
  outputs: ['markdown', 'pages'],
})

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

Explicit retry with idempotency key

idempotent-parse.ts

import { FileRouterClient } from '@file_router/sdk'

const client = new FileRouterClient()

// Using the same key on retry returns the original job result
const result = await client.parse('https://example.com/report.pdf', {
  provider: 'llamaparse',
  outputs: ['markdown'],
  idempotencyKey: 'invoice-2024-report-v1',
})

console.log(result.outputs.markdown)

The hosted service accepts documents up to 100 MB. For direct BYOK mode without this ceiling, see Direct BYOK.

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

FileRouterClient: Connect to the Hosted Service

Constructor

Constructor options

Methods

parse()

compare()

Idempotency keys

Complete example

Explicit retry with idempotency key

​Constructor

​Constructor options

​Methods

parse()

compare()

​Idempotency keys

​Complete example

​Explicit retry with idempotency key

Constructor

Constructor options

Methods

Idempotency keys

Complete example

Explicit retry with idempotency key