PDF Blocks
PricingSupport
Start Free
Go to Page

Working with files

How to supply inputs — a single file, an ordered array of files for merge, and the second image binary for image watermark — with accepted formats and sizes.

Inputs are sent as binary parts of a multipart/form-data request. Most actions take exactly one PDF in a file field, but two actions need more: merge takes an ordered array of files, and image watermark takes a second binary alongside the PDF. This page covers all three input shapes.

A single file

The default. Attach one PDF in the file field and add the action’s options as string fields:

cURLbash
curl https://api.pdfblocks.com/v1/extract_pages \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F pages='1..3' \
  -o extract.pdf

The @ in -F file=@input.pdf tells cURL to send the file’s contents. Every single-input action — watermarks, security, page operations, splits — works this way.

Multiple files — merge

Merge documents is the one action that accepts an array. Send the file field more than once, and the documents are merged in the order the parts appear in the request. Provide at least one file; you can send many in a single call.

Order is positional, so send the parts in the sequence you want them merged. When your HTTP client exposes a form object, use its append method (not set) so that repeating file adds parts instead of overwriting the previous one.

cURLbash
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@cover.pdf \
  -F file=@body.pdf \
  -F file=@appendix.pdf \
  -o merged.pdf
Pythonpython
# pip install requests
import requests

files = [
    ('file', ('cover.pdf', open('cover.pdf', 'rb'), 'application/pdf')),
    ('file', ('body.pdf', open('body.pdf', 'rb'), 'application/pdf')),
    ('file', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

response = requests.post(
    'https://api.pdfblocks.com/v1/merge_documents',
    headers={'X-API-Key': 'your_api_key'},
    files=files,
)

response.raise_for_status()
with open('merged.pdf', 'wb') as output:
    output.write(response.content)
Node.jsjavascript
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
for (const name of ['cover.pdf', 'body.pdf', 'appendix.pdf']) {
  body.append('file', new Blob([await readFile(name)]), name);
}

const response = await fetch('https://api.pdfblocks.com/v1/merge_documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('merged.pdf', Buffer.from(await response.arrayBuffer()));

If repeating the file field is awkward in your HTTP client (PHP’s cURL, Ruby’s form helpers), send numbered file_1 through file_10 fields instead — they are merged in numeric order. Use the repeated file array when you need more than ten documents.

An image alongside the PDF — image watermark

Add an image watermark takes two binary parts: the PDF in file and the watermark image in an image field. The image must be PNG or JPEG. Both parts are required.

cURLbash
curl https://api.pdfblocks.com/v1/add_image_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F image=@logo.png \
  -o watermarked.pdf

The remaining fields — transparency, margin, pages — are ordinary string options; see the action reference for their ranges and defaults.

Accepted inputs and size

  • The file input (and each merged file) must be a readable PDF. A file that can’t be parsed as a PDF returns a 400 naming the file field — see Errors.
  • The image input for image watermark must be PNG or JPEG.
  • Which pages an action touches is a separate concern from how you attach the file. Express page selections with the pages field documented in Selecting pages.

For large documents — streaming the upload and download, timeouts, and retries — see Working with large files.