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

# FileRouterClient: Connect to the Hosted Service

> Connect to the hosted FileRouter API with FileRouterClient. Reads FILEROUTER_API_KEY from your environment and handles async job polling for you.

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

```ts client.ts theme={null}
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

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

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

<ParamField body="fetch" type="typeof globalThis.fetch">
  Provide a custom `fetch` implementation. Useful in environments where the global `fetch` is unavailable or you need request interception for testing.
</ParamField>

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

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

<CardGroup cols={2}>
  <Card title="parse()" icon="file-magnifying-glass" href="/sdk/parse">
    Process a single document with one provider. Returns a `ParseResult` with normalized outputs, page count, and optional raw provider response.
  </Card>

  <Card title="compare()" icon="code-compare" href="/sdk/compare">
    Run one document through multiple providers concurrently. Returns a `CompareResult` with a `providers` array containing each provider's outcome.
  </Card>
</CardGroup>

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

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

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

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

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

<Info>
  The hosted service accepts documents up to **100 MB**. For direct BYOK mode without this ceiling, see [Direct BYOK](/sdk/direct-byok).
</Info>