API Documentation
Whipdoc is a lossless PDF compression API. One endpoint, an API key, and you're compressing. Base URL: https://www.whipdoc.com
Quickstart
Create a free account, generate an API key from your dashboard, then compress a PDF:
curl -X POST https://www.whipdoc.com/api/v1/pdf/compress \
-H "X-API-Key: pdf_live_your_key" \
-F "file=@document.pdf" \
-o compressed.pdfThe response is the compressed PDF, with size and ratio details in the response headers. That's the whole API.
Authentication
Every request is authenticated with your API key in the X-API-Key header. Keys come in two environments:
pdf_test_…— for development and testingpdf_live_…— for production
Keep your keys secret — they grant full access to your account's quota. You can revoke and rotate keys anytime from the dashboard.
Compress a PDF
POST /api/v1/pdf/compress
Send a PDF as a multipart file upload, or pass a URL to a PDF. Returns the compressed PDF (or JSON — see below).
Parameters
| Parameter | In | Description |
|---|---|---|
| file | form-data | The PDF to compress (or use url). |
| url | form-data / JSON | A public URL to a PDF, fetched server-side. |
| mode | query / form | lossless (default) or aggressive. |
| response | query | binary (default) or json. |
Response headers (binary mode)
| X-Original-Size | Input size in bytes |
| X-Compressed-Size | Output size in bytes |
| X-Compression-Ratio | Percentage saved |
| X-Compression-Mode | lossless or aggressive |
| X-Processing-Time | Processing duration |
Examples
# Upload a file
curl -X POST https://www.whipdoc.com/api/v1/pdf/compress \
-H "X-API-Key: pdf_live_your_key" \
-F "file=@document.pdf" -o out.pdf
# From a URL, JSON response
curl -X POST "https://www.whipdoc.com/api/v1/pdf/compress?response=json" \
-H "X-API-Key: pdf_live_your_key" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/doc.pdf"}'JSON response
Add ?response=json (or send Accept: application/json) to get metadata plus the base64-encoded result in one payload:
{
"originalSize": 2411008,
"compressedSize": 1198421,
"compressionRatio": "50.30%",
"bytesSaved": 1212587,
"mode": "lossless",
"engine": "qpdf",
"processingTimeMs": 240,
"filename": "document_compressed.pdf",
"data": "JVBERi0xLjcK..."
}Compression modes
lossless (default)
Repacks the PDF with object streams and maximum-level recompression. Text, vectors, and images are preserved bit-for-bit. Best for documents you can't afford to degrade.
aggressive
Additionally re-encodes images (lossy for image data) for extra savings — great for scans and photo-heavy PDFs. Whipdoc only keeps the smaller result, so aggressive is never larger than lossless.
Account & usage
GET /api/v1/account
Check your plan, limits, and remaining quota programmatically. This call is not metered — it doesn't consume an operation.
{
"plan": "pro",
"environment": "live",
"limits": {
"operationsPerMonth": 5000,
"maxFileSizeBytes": 104857600,
"rateLimitPerMinute": 120
},
"usage": {
"operationsUsed": 1284,
"operationsRemaining": 3716,
"resetsOn": "2026-07-01"
}
}Errors
Errors are returned as JSON with an error message and an appropriate status code.
| Status | Meaning |
|---|---|
| 400 | Missing/invalid file, bad URL, or not a valid PDF |
| 401 | Missing, malformed, or invalid API key |
| 413 | File exceeds your plan's size limit |
| 429 | Rate limit (per minute) or monthly quota exceeded — the body says which |
| 500 | Unexpected error processing the PDF |
Limits & plans
| Plan | Operations / mo | Max file size | Rate limit |
|---|---|---|---|
| Free | 50 | 4 MB | 10 / min |
| Starter | 1,000 | 25 MB | 60 / min |
| Pro | 5,000 | 100 MB | 120 / min |
| Scale | 20,000 | 150 MB | 600 / min |
See pricing for details. Quota resets on the first of each month (UTC). Direct file uploads are limited to 4 MB on every plan; send larger files by URL ({"url": "https://..."}) and the plan's max file size applies.
Understanding lossless compression
This is the most important thing to know about Whipdoc, so we'll be straight with you: lossless results vary a lot by file.
- A bloated PDF (uncompressed streams, redundant objects, exported from Office or a scanner) can shrink 40–70%.
- A PDF that's already well-optimized may shrink only a few percent — or not at all. That's not a bug; there's simply nothing left to remove without throwing away data.
- We never return a file larger than the input. If we can't beat it, you get your original bytes back.
If you need bigger reductions and can accept image re-encoding, use mode=aggressive. If you need the document preserved exactly (legal, archival, signed PDFs), stay on the lossless default — we won't touch a pixel.
Ready to start?
Create a free account and get 50 compressions a month, no card required.
Get your API key