PDF tools

Tools accept existing PDFs as multipart uploads (or JSON with base64 PDFs) and return a processed PDF. Each tool is metered at 1 credit per page of output, minimum 1. Uploads are limited to 10 MB per file and 20 files per request. Filenames pass through an optional filename field.

Merge

Multipart: repeat the files field once per PDF (2–20). A lone file field is also accepted and merged with files. JSON: send files as an array of base64-encoded PDFs plus an optional filename.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/merge \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "files=@part-1.pdf" \
  -F "files=@part-2.pdf" \
  --output merged.pdf

Split

One file field plus ranges. Ranges can be a page string like "1-3,5", a JSON array of [start, end] pairs, or an array of {start, end} objects (1-indexed, inclusive). There is no splitMode parameter. One range returns that part directly; several ranges are concatenated back in order into a single PDF.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/split \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "file=@report.pdf" \
  -F 'ranges=1-3,5' \
  --output split.pdf

Rotate

angle is required and must be one of 0, 90, 180 or 270 (clockwise, added to each page's existing rotation). pages is optional and defaults to all pages; give a page list like "1,3-5", a JSON array of page numbers, or a single page number. JSON mode uses file (base64), angle, pages.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/rotate \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "file=@scan.pdf" \
  -F "angle=90" \
  -F "pages=1,3-5" \
  --output rotated.pdf

Watermark

text is required (1–200 characters) and is stamped diagonally on every page. Optional: opacity between 0 and 1 (default 0.3) and fontSize between 6 and 200 (default 48). JSON mode uses file (base64), text, opacity, fontSize.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/watermark \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "file=@contract.pdf" \
  -F "text=DRAFT" \
  -F "opacity=0.3" \
  --output watermarked.pdf

Encrypt

Password-protects one PDF. userPassword is required (1–128 characters) and readers must enter it to open the file. ownerPassword is optional (max 128 characters) and sets the permissions password. JSON mode uses file (base64), userPassword, ownerPassword.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/encrypt \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "file=@private.pdf" \
  -F "userPassword=s3cr3t" \
  --output encrypted.pdf
# 200 · Content-Type: application/pdf

A successful response is 200 with Content-Type: application/pdf and a standard /Encrypt dictionary. 400 invalid_request means userPassword is missing or longer than 128 characters; 422 render_failed means the encryption engine is unavailable for this deployment — retry later, the request is not charged.

Compress

Removes document metadata (unless stripMetadata=false), re-saves the PDF with object streams, and — when the rendering engine is available — re-distils it through Ghostscript's PDF/A route to recompress image streams. The smallest valid result is returned; if nothing shrinks, the original bytes come back unchanged with X-Pdfpilot-Compress-Note: already-optimal. Responses include X-Pdfpilot-Saved-Bytes and X-Pdfpilot-Compress-Strategy(pdf-lib, gotenberg-pdfa or original). Already compressed or scanned PDFs may not shrink; PDF/A conversion can alter colour profiles.

curl -X POST https://www.pdfpilot24.com/api/v1/tools/compress \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -F "file=@scan.pdf" \
  -i --output compressed.pdf

JSON (base64) alternative

Every tool also accepts application/json: single-file tools take file as one base64 PDF (merge takes files as an array), with the same option fields. Useful when multipart uploads are awkward.

FILE=$(base64 -w0 contract.pdf)
curl -X POST https://www.pdfpilot24.com/api/v1/tools/watermark \
  -H "Authorization: Bearer $PDFPILOT_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file\":\"$FILE\",\"text\":\"DRAFT\"}" \
  --output watermarked.pdf