API Documentation

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.pdf

The 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 testing
• pdf_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

Response headers (binary mode)

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

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.

Limits & plans

See pricing for details. Quota resets on the first of each month (UTC).

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.