---
title: "Uploading from your server"
description: "Upload PDFs where they arrive, into a folder and with a name, and keep each document's id with your own records. Or let CloudPDF fetch them from a URL."
source: "https://www.cloudpdf.com/docs/platform/app/uploads"
---

# Uploading from your server

When your users send you PDFs, or your app makes them, upload them from your server. Keep each
document's id with your own record, so you can open it later with a token or a grant.

```ts
const { document } = await cloudpdf.uploads.create({
  tenantId,
  source: file,
  name: 'Support agreement.pdf',
  folderId: clientsFolderId,
});

await db.contracts.update(contract.id, { documentId: document.id });
```

The API key needs **Documents and folders** on Write. The document shows up in the dashboard right
away, in its folder.

When your users pick the PDF in your app, let their browser
[upload it straight to CloudPDF](https://www.cloudpdf.com/docs/platform/app/browser-uploads.md) instead. The file never passes
through your server.

## What you can upload

`source` takes the PDF however you have it:

| `source`                        | For example                                               |
| :------------------------------ | :-------------------------------------------------------- |
| A `File` or `Blob`              | A file from a form, in a Next.js server action            |
| A `Uint8Array` or `ArrayBuffer` | Bytes you made or received, such as `req.body` in Express |
| `{ path }`                      | A file on your server's disk, in Node                     |

CloudPDF reads the PDF as it is: forms, signatures, attached files, bookmarks and all.

## Name, folder and your own data

| Field      | What it does                                                                             |
| :--------- | :--------------------------------------------------------------------------------------- |
| `name`     | What the dashboard shows, such as `Support agreement.pdf`. Without it, the document's id |
| `folderId` | The folder it goes into. Without it, the top level                                       |
| `metadata` | Your own data, such as `{ contractId: 'c_381' }`, returned with the document             |

## The same file twice

Every upload makes a new document, even of a file you uploaded before. To get the existing one
back instead, say so:

```ts
const { status, document } = await cloudpdf.uploads.create({
  tenantId,
  source: file,
  dedupMode: 'reuse-existing',
});
```

`status` is `'deduped'` when CloudPDF already had the file, and `'created'` when it's new. With an
`idempotencyKey`, it can also be `'resumed'`: an earlier upload with that key hadn't finished.

For retries, give the upload an `idempotencyKey`: the same key twice makes one document, so a
request that timed out can safely run again.

## Large files

`uploads.create` sends the file from your server straight to storage whenever CloudPDF gives it a
storage link, and through CloudPDF's API otherwise. For a large file on disk, give it `{ path }`:
going straight to storage, the file is read as it's sent, never held in memory whole.

`onProgress` reports the bytes sent as they go, and `signal` stops the upload:

```ts
const controller = new AbortController();

await cloudpdf.uploads.create({
  tenantId,
  source: { path: '/var/uploads/site-survey-scans.pdf' },
  onProgress: (loaded, total) => {
    console.log(`${Math.round((loaded / total) * 100)}%`);
  },
  signal: controller.signal,
});
```

## From a URL

When the PDF is somewhere CloudPDF can reach, such as a storage bucket with a presigned link, let
CloudPDF fetch it, and skip your server's bandwidth:

```ts
const { document } = await cloudpdf.documents.importFrom({
  tenantId,
  source: { kind: 'url', url: presignedUrl },
  name: 'Q3 2026 report.pdf',
});
```

The URL must be https, and its answer must say how large the file is. Treat it as a secret, since
it opens the file. CloudPDF never shows its query string in an error or a log.

## Good to know

- **Uploading isn't opening.** Whoever opens the document gets a [token](https://www.cloudpdf.com/docs/platform/app/tokens.md)
  or a [grant](https://www.cloudpdf.com/docs/platform/grants.md), and never needs to know where it came from.
- **Every option** is in the API reference: [Initialize an upload](https://www.cloudpdf.com/docs/api-reference/documents/init.md)
  and [Import from a URL](https://www.cloudpdf.com/docs/api-reference/documents/import-from.md).

* [Uploads from the browser](https://www.cloudpdf.com/docs/platform/app/browser-uploads.md) — Let your users' browsers upload PDFs straight to CloudPDF.
* [Tokens for your users](https://www.cloudpdf.com/docs/platform/app/tokens.md) — Open the document you uploaded, for one signed-in user.
* [Uploading in the dashboard](https://www.cloudpdf.com/docs/platform/documents/uploading.md) — Drop PDFs on the page, into folders.
