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.
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 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:
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:
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:
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 or a grant, and never needs to know where it came from.
- Every option is in the API reference: Initialize an upload and Import from a URL.