Skip to main content

Uploading to Your S3 Bucket

Use customS3PresignedUrl when you want PDFBolt to upload the output PDF directly to your own S3-compatible storage. This keeps the final PDF in your storage environment, where you control retention, access policies, and further processing.

Endpoint support

customS3PresignedUrl works with /v1/sync, /v1/async, and PDF Tools Sync endpoints (/v1/tools/*/sync) on paid plans.

Omit this parameter to use PDFBolt's default storage. The PDF stays available via documentUrl for 24 hours.

How It Works​

  1. Generate an HTTPS presigned PUT URL for the final PDF object in your S3-compatible bucket.
  2. Send the URL as customS3PresignedUrl in a /v1/sync, /v1/async, or PDF Tools Sync (/v1/tools/*/sync) request.
  3. PDFBolt generates or processes the PDF and uploads it to the presigned URL with an HTTP PUT.
  4. Your application reads and manages the PDF from your own bucket.

The presigned PUT URL is for uploading only. To download a private PDF, use your storage SDK or generate a presigned GET URL.

Presigned URL Requirements​

The URL you pass to PDFBolt must:

  • Use HTTPS. HTTP URLs are rejected.
  • Be no longer than 2048 characters.
  • Allow PUT for the exact bucket and object key.
  • Remain valid until the upload completes, including any conversion retries.
  • Accept Content-Type: application/pdf.
  • Accept the Content-Disposition header PDFBolt sends during upload.

By default, the Conversion API uploads with:

Content-Type: application/pdf
Content-Disposition: inline

PDF Tools also include the output filename, for example Content-Disposition: inline; filename="compress.pdf". The default filenames are merge.pdf, compress.pdf, and convert-pdfx.pdf.

If either upload header is included in the signature, its value must exactly match the value sent by PDFBolt. When your request includes contentDisposition or filename, generate the presigned URL with the matching Content-Disposition value.

Supported S3-Compatible Storage​

PDFBolt can upload to S3-compatible storage services that support HTTPS presigned PUT URLs, including:

  • Amazon S3
  • Cloudflare R2
  • DigitalOcean Spaces
  • MinIO
  • Wasabi
  • Backblaze B2
Other S3-Compatible Storage

Other S3-compatible storage services may work if they support HTTPS presigned PUT URLs and the required upload headers.

Example: Generating a Presigned URL in Node.js​

Install the AWS SDK v3 packages:

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
generatePresignedUrl.cjs
const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');

const s3 = new S3Client({
requestChecksumCalculation: 'WHEN_REQUIRED',
region: process.env.S3_REGION || 'us-east-1',
...(process.env.S3_ENDPOINT ? { endpoint: process.env.S3_ENDPOINT } : {}),
credentials: {
accessKeyId: process.env.S3_ACCESS_KEY_ID,
secretAccessKey: process.env.S3_SECRET_ACCESS_KEY
},
// Some S3-compatible providers, such as MinIO, require path-style URLs.
forcePathStyle: process.env.S3_FORCE_PATH_STYLE === 'true'
});

async function generatePresignedUrl(bucketName, objectKey) {
const command = new PutObjectCommand({
Bucket: bucketName,
Key: objectKey,
ContentType: 'application/pdf',
ContentDisposition: process.env.S3_CONTENT_DISPOSITION || 'inline'
});

const url = await getSignedUrl(s3, command, { expiresIn: 3600 });
console.log(url);
return url;
}

generatePresignedUrl('your-bucket-name', `pdfbolt/document-${Date.now()}.pdf`)
.catch((error) => {
console.error('Error generating presigned URL:', error);
process.exit(1);
});

Replace your-bucket-name with your bucket name and set the environment variables for your storage provider. Set S3_REGION to the region required by your provider.

Run the script with your storage credentials
S3_REGION=us-east-1 \
S3_ACCESS_KEY_ID=your-access-key-id \
S3_SECRET_ACCESS_KEY=your-secret-access-key \
node generatePresignedUrl.cjs

For S3-compatible providers other than AWS S3, also set S3_ENDPOINT. For providers that require path-style URLs, set S3_FORCE_PATH_STYLE=true.

The output should look like this:

https://your-bucket.s3.amazonaws.com/pdfbolt/document-1714580000000.pdf?<presigned-query-params>
Presigned URL Best Practices
  • Use a unique object key for each PDF and generate a presigned URL for that key. Uploading to an existing key can overwrite the object.
  • Generate the URL on your server, not in browser code.
  • Keep storage credentials in environment variables or a secret manager.
  • Store the bucket and object key in your application so you can find the PDF later without relying on the presigned URL.

Use the Presigned URL with PDFBolt​

Replace the example upload URL with the URL generated by your script.

Sync Conversion​

Use the generated URL as customS3PresignedUrl in the /v1/sync request body:

{
"url": "https://example.com",
"customS3PresignedUrl": "https://your-bucket.s3.amazonaws.com/pdfbolt/document.pdf?<presigned-query-params>"
}

When the upload succeeds, the response has documentUrl: null, expiresAt: null, and isCustomS3Bucket: true because the PDF is already in your bucket.

Sync response with custom S3
{
"requestId": "09dd133a-a064-44b6-80f5-b2a7571f77ed",
"status": "SUCCESS",
"errorCode": null,
"errorMessage": null,
"documentUrl": null,
"expiresAt": null,
"isAsync": false,
"duration": 664,
"documentSizeMb": 0.02,
"isCustomS3Bucket": true
}

Async Conversion​

For /v1/async, include both webhook and customS3PresignedUrl. Replace https://your-app.com/webhooks/pdfbolt with your HTTPS webhook URL:

{
"url": "https://example.com",
"webhook": "https://your-app.com/webhooks/pdfbolt",
"customS3PresignedUrl": "https://your-bucket.s3.amazonaws.com/pdfbolt/document.pdf?<presigned-query-params>"
}

The initial API response returns a requestId. After the PDF is generated and uploaded, PDFBolt attempts to deliver a signed webhook with documentUrl: null, expiresAt: null, and isCustomS3Bucket: true.

Async webhook with custom S3
{
"requestId": "fadb0a9c-a5f5-4d15-8588-b15bde7c201d",
"status": "SUCCESS",
"errorCode": null,
"errorMessage": null,
"documentUrl": null,
"expiresAt": null,
"isAsync": true,
"duration": 601,
"documentSizeMb": 0.02,
"isCustomS3Bucket": true
}

See Async Workflow Details for the full async flow.

PDF Tools Sync Endpoints​

Include customS3PresignedUrl in a PDF Tools Sync request. For example, send this body to /v1/tools/compress/sync:

{
"url": "https://pdfbolt.com/samples/pdf-compression-sample.pdf",
"customS3PresignedUrl": "https://your-bucket.s3.amazonaws.com/pdfbolt/compressed.pdf?<presigned-query-params>"
}
Signed upload headers

If you use the Node.js script above, set S3_CONTENT_DISPOSITION to inline; filename="compress.pdf" for this example. This matches the default header sent by Compress.

Merge (/v1/tools/merge/sync) and PDF/X (/v1/tools/convert-pdfx/sync) also support this option. On success, documentUrl and expiresAt are null, and isCustomS3Bucket is true.

Troubleshooting​

Upload Error​

When PDFBolt receives a non-2xx response while uploading the PDF to your presigned URL, the operation fails with errorCode: "CUSTOM_S3_UPLOAD_ERROR". For /v1/sync and PDF Tools Sync endpoints (/v1/tools/*/sync), PDFBolt returns the error in an HTTP 400 response.

For /v1/async, if no conversion retries remain, PDFBolt attempts to deliver a final webhook with status: "FAILURE". In both cases, the errorMessage includes the storage provider's response code and body.

An upload timeout also returns CUSTOM_S3_UPLOAD_ERROR, with errorMessage set to "Custom S3 upload timed out".

Check the following possible causes:

  • The presigned URL expired before the PDF upload started.
  • The URL doesn't allow PUT for the exact bucket/key.
  • The signing identity doesn't have s3:PutObject or equivalent write permission.
  • The bucket or object key is wrong.
  • The provider rejected an upload header, usually Content-Type or Content-Disposition.
  • The bucket policy or provider allowlist rejects PDFBolt's upload request.

If your storage provider uses IP allowlisting, see PDFBolt IP Addresses.

Presigned URL Rejected Before Conversion​

Make sure customS3PresignedUrl uses HTTPS and is no longer than 2048 characters. HTTP URLs and longer URLs are rejected before PDF generation starts.

Next Steps​