# JavaScript (/docs/sdks/javascript)





The Paperful JavaScript SDK provides a typed interface for interacting with the [Paperful API](/docs/api) from JavaScript and TypeScript applications.

It works with modern server runtimes including Node.js and Bun.

## Installation [#installation]

The Paperful JavaScript SDK is available on npm.

<Cards>
  <Card icon="<IconBrandNpm className=&#x22;size-4&#x22; />" title="npm" href="https://www.npmjs.com/package/@paperful/sdk">
    View package versions, release information, and installation details.
  </Card>

  <Card icon="<IconBrandGithub className=&#x22;size-4&#x22; style={{fill: &#x22;currentColor&#x22;}} />" title="Source Code" href="https://github.com/paperful-io/paperful-js">
    View the source code, contribute, and explore the repository.
  </Card>
</Cards>

Install the SDK using your preferred package manager.

<Tabs items="['npm', 'yarn', 'pnpm', 'bun']">
  <Tab value="npm">
    ```bash
    npm install @paperful/sdk
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @paperful/sdk
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @paperful/sdk
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @paperful/sdk
    ```
  </Tab>
</Tabs>

## Create a client [#create-a-client]

Initialize the SDK with your [API key](/docs/platform/api-keys):

```ts
import { Paperful } from "@paperful/sdk";

const paperful = new Paperful({
  // optional: provide your API key here if not using environment variables
  apiKey: "pf_..."
});
```

<Callout type="warn">
  Keep your API key on the server. Do not expose it in client-side applications or commit it to source control. 
</Callout>

## TypeScript [#typescript]

The JavaScript SDK includes TypeScript definitions out of the box.

Responses are fully typed, giving you autocomplete and compile-time validation throughout your application. The types you'll most often need are exported from the package:

```ts
import type {
  AnyPaperNode,
  MetadataFilter,
  PaperMetadata,
  PaperNodeType,
  SearchEvent,
  SearchResult,
  SearchResultItem,
} from "@paperful/sdk";
```

| Type                               | Description                                                                                                                                |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `AnyPaperNode`                     | A node of the [paper graph](/docs/sdks/papers/graph). Checking its `type` narrows its `data`.                                              |
| `PaperNodeType`                    | Every node type, such as `"table"` or `"paragraph_title"`.                                                                                 |
| `PaperMetadata`                    | The [metadata](/docs/sdks/papers/metadata) attached to a paper.                                                                            |
| `MetadataFilter`                   | A filter for [listing](/docs/sdks/papers/list#filter-by-metadata) and [searching](/docs/sdks/search/query#filter-by-metadata) by metadata. |
| `SearchResult`, `SearchResultItem` | The [search](/docs/sdks/search/query) response and each of its results.                                                                    |
| `SearchEvent`, `PaperUploadEvent`  | The events received while [searching](/docs/sdks/search/query#stream-search-progress) or [uploading](/docs/sdks/papers/upload).            |

The schema of each node type, such as `PaperTableNodeSchema`, and of its data, such as `NodeTableData`, are exported as well, along with a class for each [error](/docs/sdks/errors), such as `NotFound` and `ValidationError`.

## Runtime support [#runtime-support]

The SDK is designed for modern server-side JavaScript runtimes.

| Runtime    | Support         |
| ---------- | --------------- |
| Node.js    | Supported       |
| Bun        | Supported       |
| TypeScript | Supported       |
| Serverless | Supported       |
| Browser    | Not recommended |

The SDK must be used from backend or server-side environments.

## Guides [#guides]

<Cards>
  <Card title="Upload a paper" href="/docs/sdks/papers/upload">
    Upload a document and track its processing.
  </Card>

  <Card title="Read the paper graph" href="/docs/sdks/papers/graph">
    Load a paper's nodes and move between them.
  </Card>

  <Card title="Search papers" href="/docs/sdks/search/query">
    Search the content of every paper in your workspace.
  </Card>

  <Card title="Search to context" href="/docs/sdks/search/context">
    Turn search results into focused context for a model.
  </Card>
</Cards>
