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. Every step is also available through the REST API.
Before You Start
You need:
- A Paperful account
- An API Key
- A document to upload, such as a PDF or image-based document
Install the SDK
npm install @paperful/sdk Store your API key in the PAPERFUL_API_KEY environment variable, then create a client:
import { Paperful } from "@paperful/sdk";
const paperful = new Paperful(); // reads PAPERFUL_API_KEY Upload a Paper
Send your document to Paperful. When the upload succeeds, Paperful creates a Paper. 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.
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.
Treat the Paper ID as the stable reference to a document in Paperful. Store it alongside the corresponding record in your application.
For more details, see Upload a paper.
Read the Paper Graph
Once processed, retrieve the Paper's structured representation.
The Paper 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
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, or see Read the paper graph for SDK examples.
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
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.
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.
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 and Get a node's context.
Next steps
- Papers: how papers are processed and their lifecycle.
- Handle errors: catch and respond to API errors.
- MCP: connect AI assistants to your papers without writing code.