> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia

> MarkpdfClient class, useConvertFile hook and @markpdf/react-native types.

# Referencia

## `MarkpdfClient`

```ts theme={null}
import { MarkpdfClient } from "@markpdf/react-native";

const client = new MarkpdfClient({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.markpdf.tech", // optional, production default
});
```

<ParamField body="apiKey" type="string" required>
  Tu API key.
</ParamField>

<ParamField body="baseUrl" type="string" default="https://api.markpdf.tech">
  URL base of API.
</ParamField>

Unlike SDK of Node.js, this client is standalone: ​​it does not wrap `@markpdf/sdk`, it implements the calls directly on the `fetch`/`FormData` globals of React Native.

## Methods

### `convertLocalFile`

```ts theme={null}
client.convertLocalFile(
  file: { uri: string; name: string; mimeType?: string },
  options?: ConvertOptions
): Promise<ConvertResult>
```

Upload a local file (from a picker) via `POST /convert` (multipart/form-data), using the `{ uri, name, type }` format that React Native recognizes in `FormData` to attach files without reading them in JS.

<ParamField body="file.uri" type="string" required>
  URI local to the file (`file://...` or `content://...`), as returned by the picker.
</ParamField>

<ParamField body="file.name" type="string" required>
  File name to send.
</ParamField>

<ParamField body="file.mimeType" type="string" default="application/octet-stream">
  Content-Type of the file.
</ParamField>

### `convertFromUrl`

```ts theme={null}
client.convertFromUrl(
  url: string,
  filename?: string,
  options?: ConvertOptions
): Promise<ConvertResult>
```

Calls `POST /convert/from-url` with a body JSON — does not upload any files, API downloads URL server-side.

<ParamField body="url" type="string" required>
  URL public (or signed) of the document to be converted. The API is downloaded directly; It does not go through the device.
</ParamField>

<ParamField body="filename" type="string">
  File name to associate with the result. If omitted, API attempts to infer it from URL.
</ParamField>

<ParamField body="options" type="ConvertOptions">
  Same options as `convertLocalFile`.
</ParamField>

### `pdfIndex`

```ts theme={null}
client.pdfIndex(url: string, filename?: string): Promise<Record<string, unknown>>
```

Call `POST /pdf/index`. Returns the spine of PDF without converting it — useful for an agent to decide what range of `pages` to request before spending a full conversion. See [`POST /pdf/index`](/docs/api/pdf-index).

### `getJob` / `waitForJob`

```ts theme={null}
client.getJob(jobId: string): Promise<Job>

client.waitForJob(
  jobId: string,
  options?: { pollIntervalMs?: number; timeoutMs?: number }
): Promise<Job>
```

<ParamField body="jobId" type="string" required>
  Job identifier (`job_id`) returned by API when `202` responds.
</ParamField>

<ParamField body="options.pollIntervalMs" type="number" default="5000">
  Milliseconds between each `GET /jobs/{id}`.
</ParamField>

<ParamField body="options.timeoutMs" type="number">
  If specified, `waitForJob` throws a generic `Error` upon passing without the job having finished. Without `timeoutMs`, it polls indefinitely until `completed` or `failed`.
</ParamField>

`getJob` queries `GET /jobs/{id}` only once and returns `Job` as it is (may follow `"queued"` or `"processing"`). `waitForJob` does repeated poll until `status` is `"completed"` or `"failed"`:

* If `status === "failed"`, `waitForJob` launches `JobFailedError` (does not return the failed job, launches).
* If `status === "completed"`, returns `Job` with `body` populated (`string` or `JsonResult` depending on `responseFormat` of the original job).
* If `timeoutMs` is exceeded, throws a generic `Error` (not `MarkpdfError`).

## `ConvertOptions`

```ts theme={null}
interface ConvertOptions {
  inputFormat?: "auto" | "pdf" | "docx" | "csv" | "txt" | "xlsx" | "pptx" | "zip";
  mode?: "fast" | "ultra_fast" | "balanced" | "quality" | "auto";
  clean?: boolean;              // default true
  imageOcr?: boolean;           // default false
  hybridOcr?: boolean;          // default false
  responseFormat?: "markdown" | "json"; // default "markdown"
  slim?: boolean;                // default false
  pages?: string;
  autoPoll?: boolean;            // default true
  pollIntervalMs?: number;       // default 5000
}
```

All fields are optional; they apply to `convertLocalFile`, `convertFromUrl` and `convert()` of `useConvertFile`.

<ParamField body="inputFormat" type="&#x22;auto&#x22; | &#x22;pdf&#x22; | &#x22;docx&#x22; | &#x22;csv&#x22; | &#x22;txt&#x22; | &#x22;xlsx&#x22; | &#x22;pptx&#x22; | &#x22;zip&#x22;" default="auto">
  Input file format. `"auto"` detects it by extension/content. Set this explicitly if you upload a file without a reliable extension (for example an Android `content://` URI with no clear name).
</ParamField>

<ParamField body="mode" type="&#x22;fast&#x22; | &#x22;ultra_fast&#x22; | &#x22;balanced&#x22; | &#x22;quality&#x22; | &#x22;auto&#x22;" default="fast">
  Conversion speed/quality profile. `"ultra_fast"` prioritizes latency, `"quality"` prioritizes fidelity of the resulting Markdown, `"auto"` lets the backend decide based on the document.
</ParamField>

<ParamField body="clean" type="boolean" default="true" />

<ParamField body="imageOcr" type="boolean" default="false" />

<ParamField body="hybridOcr" type="boolean" default="false" />

<ParamField body="responseFormat" type="&#x22;markdown&#x22; | &#x22;json&#x22;" default="markdown">
  If it is `"json"`, the resolved response is an object [`JsonResult`](#tipos) with metadata (`engine`, `size_bytes`, `timings`, etc.) in addition to the Markdown. With `"markdown"` (default), the resolved response is directly `string`.
</ParamField>

<ParamField body="slim" type="boolean" default="false">
  Reduces Markdown to a more compact version (less spacing/redundant metadata), intended to minimize tokens in RAG/LLM pipelines.
</ParamField>

<ParamField body="pages" type="string">
  Page range 1-based, only applies to PDF. Examples: `"1,3,5-10"`, `"120-145"`. Useful on mobile to avoid uploading/processing entire documents of hundreds of pages when you only need one section.
</ParamField>

<ParamField body="autoPoll" type="boolean" default="true">
  If API responds `202` (saturated backends), `convertLocalFile`/`convertFromUrl` do automatic polling via `waitForJob` until the job finishes. `useConvertFile` **does not** honor this option — it always requires manual handling of `202` because it uses `XMLHttpRequest` instead of `waitForJob`. See [Streaming and asynchronous jobs](/docs/sdks/react-native/streaming-and-async).
</ParamField>

<ParamField body="pollIntervalMs" type="number" default="5000">
  Interval between each poll to `GET /jobs/{id}` when `autoPoll` is active.
</ParamField>

## `useConvertFile(client)`

```ts theme={null}
function useConvertFile(client: MarkpdfClient): {
  convert: (file: LocalFile, options?: ConvertOptions) => Promise<ConvertResult | undefined>;
  reset: () => void;
  status: "idle" | "uploading" | "converting" | "success" | "error";
  progress: number;
  markdown: string | null;
  json: JsonResult | null;
  error: MarkpdfError | null;
}
```

Same as `convertLocalFile`, but with upload progress via `XMLHttpRequest` (RN implements `XMLHttpRequest` globally, unlike the browser with only `fetch`). Takes client as argument — does not use context/Provider.

## Tipos

```ts theme={null}
import type {
  ConvertOptions,
  ConvertResult,
  Job,
  JsonResult,
  LocalFile,
  InputFormat,
  Mode,
  ResponseFormat,
  JobStatus,
} from "@markpdf/react-native";
```

```ts theme={null}
interface LocalFile {
  uri: string;
  name: string;
  mimeType?: string;
}

interface Job {
  job_id: string;
  status: "queued" | "processing" | "completed" | "failed";
  body?: string | JsonResult;
  error?: string;
}

type ConvertResult = string | JsonResult | Job;
```

`ConvertResult` is `Job` only if `autoPoll: false` and API responded `202`; otherwise `convertLocalFile`/`convertFromUrl` have already resolved the job internally.