# Quickstart (/docs/quickstart)



In this guide, you will learn how to use Paperful to upload a document, process it into structured content, and search across your Papers.

The examples use the [JavaScript SDK](/docs/sdks/javascript). Every step is also available through the [REST API](/docs/api).

## Before You Start [#before-you-start]

You need:

* [ ] A Paperful account
* [ ] An [API Key](/docs/platform/api-keys)
* [ ] A document to upload, such as a PDF or image-based document

<Steps>
  <Step>
    ### Install the SDK [#install-the-sdk]

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

    Store your API key in the `PAPERFUL_API_KEY` environment variable, then create a client:

    ```ts title="index.ts"
    import { Paperful } from "@paperful/sdk";

    const paperful = new Paperful(); // reads PAPERFUL_API_KEY
    ```
  </Step>

  <Step>
    ### Upload a Paper [#upload-a-paper]

    Send your document to Paperful. When the upload succeeds, Paperful creates a [Paper](/docs/core-concepts/papers). A Paper is the persistent record for a document and its processed output.

    By default, `upload` waits until processing finishes and returns the ready paper.

    ```ts title="index.ts"
    import { readFile } from "node:fs/promises";

    const file = await readFile("./report.pdf");

    const paper = await paperful.papers.upload({
      file,
      fileName: "report.pdf",
    });

    console.log(paper.id, paper.status);
    ```

    Save the Paper ID in your application. You will use it to retrieve the Paper and its processed content later.

    <Callout type="tip">
      Treat the Paper ID as the stable reference to a document in Paperful. Store it
      alongside the corresponding record in your application.
    </Callout>

    For more details, see [Upload a paper](/docs/sdks/papers/upload).
  </Step>

  <Step>
    ### Read the Paper Graph [#read-the-paper-graph]

    Once processed, retrieve the Paper's structured representation.

    The [Paper Graph](/docs/core-concepts/graph) describes the document as an ordered list of nodes instead of a single unstructured text value. A Paper can contain nodes such as:

    * Titles and headings
    * Paragraphs and text blocks
    * Tables
    * Images
    * Other document structures

    ```ts title="index.ts"
    const graph = await paperful.papers.graph(paper.id);

    for (const node of graph.nodes) {
      console.log(node.position, node.type, node.page);
    }
    ```

    Use the graph when your application needs document-aware behavior, such as:

    * Rendering extracted document content
    * Finding a table or image
    * Preserving heading structure
    * Sending selected document sections to an AI model
    * Building citations back to document elements

    Learn more in [Paper Graph](/docs/core-concepts/graph), or see [Read the paper graph](/docs/sdks/papers/graph) for SDK examples.
  </Step>

  <Step>
    ### Search your Papers [#search-your-papers]

    After Papers are processed, search across your document collection.

    Paperful supports document search for workflows such as:

    * Finding relevant source material for an AI assistant
    * Looking up content across uploaded files
    * Retrieving supporting passages before generating a response
    * Building document search into an internal tool

    ```ts title="index.ts"
    const { items } = await paperful.search.query("What are the payment terms?");

    for (const result of items) {
      console.log(result.paper.fileName, result.score);
      console.log(result.content);
    }
    ```

    Each result includes the matching passage, the paper it belongs to and the nodes it came from, with their pages.

    Learn more in [Search papers](/docs/sdks/search/query).
  </Step>

  <Step>
    ### Build context for a model [#build-context-for-a-model]

    Expand a search match with the nodes around it to give a model a focused passage instead of a whole paper.

    ```ts title="index.ts"
    const [result] = items;

    const resultGraph = await paperful.papers.graph(result.paper.id);
    const node = resultGraph.nodes.find((n) => n.id === result.nodes[0].id);

    const context = await node?.context({ before: 3, after: 3 });
    ```

    Learn more in [Search to context](/docs/sdks/search/context) and [Get a node's context](/docs/sdks/papers/context).
  </Step>
</Steps>

## Next steps [#next-steps]

* [Papers](/docs/core-concepts/papers): how papers are processed and their lifecycle.
* [Handle errors](/docs/sdks/errors): catch and respond to API errors.
* [MCP](/docs/mcp): connect AI assistants to your papers without writing code.
