# Papers (/docs/core-concepts/papers)



A **paper** is the fundamental unit of content in Paperful.

When you upload a document, Paperful creates a paper and processes its contents into a structured, searchable representation that can be accessed through the [API](/docs/api), [SDKs](/docs/sdks), and [MCP](/docs/mcp).

A paper isn't just the original file. It represents the document and everything Paperful learns about it.

## Creating a paper [#creating-a-paper]

A paper is created by [uploading a document](/docs/sdks/papers/upload).

<Tabs items="['JavaScript', 'cURL']">
  <Tab value="JavaScript">
    ```ts
    const paper = await paperful.papers.upload(); 
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl -X POST https://api.paperful.io/v1/papers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@document.pdf"
    ```
  </Tab>
</Tabs>

Paperful returns the paper as soon as the upload is accepted. Processing continues asynchronously.

<Callout>
  You don't need to keep the connection open while a paper is processing. You can [retrieve its status later](/docs/sdks/papers/retrieve) or use streaming when you need real-time processing updates.
</Callout>

## Processing [#processing]

After a paper is uploaded, Paperful runs it through the processing pipeline.

Depending on the document, this may include:

* Validating the file
* Converting to other formats
* Extracting digital text
* OCR
* Layout recognition
* Extracting and understanding tables, images, charts, and other regions
* Building the [Paper Graph](/docs/core-concepts/graph)
* Generating searchable content
* Indexing the paper for semantic and full-text search

The result is a representation of the document that preserves both its content and structure.

You don't need to orchestrate these operations individually. They are part of the Paperful processing pipeline.

## Paper status [#paper-status]

A paper moves through a small set of states during its lifecycle.

| Status       | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `pending`    | The paper has been accepted and is waiting for processing. |
| `processing` | Paperful is processing the document.                       |
| `ready`      | Processing completed and the paper is ready to use.        |
| `failed`     | Processing couldn't be completed.                          |

You can retrieve the current state at any time:

```ts
const paper = await paperful.papers.get("paper_...");
console.log(paper.status);
```

Applications that need to react to processing progress can also listen to the [upload stream](/docs/sdks/papers/upload#track-progress).

## Paper content [#paper-content]

Once processing completes, the document is available as structured content.

Instead of treating a document as one large block of text, Paperful represents its contents as individual elements such as:

<Mermaid
  chart="
flowchart LR
A[&#x22;Title&#x22;]
B[&#x22;Paragraph&#x22;]
C[&#x22;Section Title&#x22;]
D[&#x22;Image&#x22;]
E[&#x22;Table&#x22;]
F[&#x22;...&#x22;]

A --> B --> C --> D --> E --> F
"
/>

These elements become Paper Nodes and together form the [Paper Graph](/docs/core-concepts/graph).

This structure makes it possible to navigate a document, retrieve specific parts, build context for AI applications, and understand relationships between its contents.

## Searching papers [#searching-papers]

Processed papers are automatically prepared for search.

Paperful can make document content available through these [search modes](/docs/sdks/search/query#choose-a-search-mode):

* Hybrid search
* Full-text only search
* Semantic only search

For example:

```ts
const results = await paperful.search({
  query: "quarterly revenue growth",
});
```

Search results point back to the relevant parts of a paper, allowing your application to [move from a search result into the document structure](/docs/core-concepts/graph#from-search-to-context).

## Retrieving a paper [#retrieving-a-paper]

You can retrieve a paper using its ID:

```ts
const paper = await paperful.papers.get("paper_...");
```

The paper object contains document-level information such as its name, status, page count, timestamps, and other metadata.

For the document's actual contents, use the content or [graph](/docs/sdks/papers/graph) APIs.

## Metadata [#metadata]

You can attach your own metadata to a paper, such as a category, a customer ID or an amount. Paperful stores it with the paper and returns it wherever the paper appears, including search results.

```ts
const paper = await paperful.papers.upload({
  file,
  metadata: { category: "invoice", customerId: "cus_123", amount: 150 },
});
```

Metadata values can be:

* Strings, numbers or booleans
* Arrays of a single type, such as `["urgent", "q3"]`
* Objects, nested up to 3 levels

Use metadata to narrow down [lists](/docs/sdks/papers/list#filter-by-metadata) and [searches](/docs/sdks/search/query#filter-by-metadata) to the papers you care about:

```ts
const results = await paperful.search.query("total amount", {
  metadata: { category: "invoice", amount: { gte: 100 } },
});
```

You can [update metadata](/docs/sdks/papers/metadata) at any time without reprocessing the paper. See [Limits](/docs/platform/limits#metadata) for the maximum size of metadata.

## Paper IDs [#paper-ids]

Every paper receives a unique ID when it is created.

```text
paper_...
```

Use this ID when [retrieving](/docs/sdks/papers/retrieve), searching, [downloading](/docs/sdks/papers/download), or [deleting](/docs/sdks/papers/delete) the paper.

Paper IDs are stable for the lifetime of the paper and should be stored by applications that need to reference the document later.

## Deleting a paper [#deleting-a-paper]

Deleting a paper removes the paper and the resources associated with it.

```ts
await paperful.papers.delete("paper_...");
```

This includes its processed content and search indexes.

<Callout type="warning">
  Deleting a paper is permanent and can't be undone.
</Callout>
