Inkspan › Guides › How to compress a PDF in cURL

How to compress a PDF in cURL

PDFs grow for boring reasons: orphaned objects left behind by edits, duplicated resources, and uncompressed streams. The /v1/pdf/compress endpoint performs a lossless structural cleanup — garbage collection of unreferenced objects, stream deflation, and removal of redundant data — and returns a smaller file with identical visual output.

Because the optimisation is structural rather than lossy, savings depend entirely on the input. Files exported from design tools or edited repeatedly often shrink substantially; a lean, freshly-generated PDF may barely move.

Also in: Python · Node.js

cURL example

curl -X POST https://api.inkspan.dev/v1/pdf/compress \
  -H "X-API-Key: ink_live_..." \
  -F "file=@input.pdf" \
  --output compressed.pdf

Request parameters

Name	Type	Required	Description
`file`	file	yes	The PDF to compress.

Response

Returns a PDF as a binary stream with Content-Type: application/pdf and Content-Disposition: attachment; filename=compressed.pdf. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

This is lossless. Images are not downsampled or re-encoded, so a scan-heavy PDF will not shrink dramatically — resample images before uploading if that is your bottleneck.
Savings vary enormously by source. Measure on your real documents rather than assuming a ratio.
A file already optimised can come back close to its original size. That is correct behaviour, not a failure.
Compare sizes after the call and keep the smaller of input and output if you need a guarantee.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

Will text stay selectable?

Yes. Compression is structural, so text, fonts, and metadata are preserved and the document remains searchable.

Can I choose a compression level?

No. The endpoint applies one lossless profile — garbage collection, deflation, and cleanup — with no quality trade-off to tune.

Why did my file get barely smaller?

It was probably already well-formed. Lossless optimisation can only remove waste, and some files have very little.

Get a free API key →

Related Manipulate guides: merge PDF files · split a PDF into pages · add a watermark to a PDF · convert a PDF to images · fill a PDF form