PDF compression for your application.

Quick start

Create a compression with a public HTTPS URL. The API accepts the work and returns 202 Accepted with a BeaglePDF job tag.

curl --fail-with-body -X POST 'https://api.beaglepdf.com/v1/compressions' \
  -H 'Authorization: Bearer bgp_live_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 9892ef96-0557-44b7-a9dc-e4f44dff2c11' \
  --data '{
    "source_url": "https://files.example.com/report.pdf",
    "compression_level": "standard",
    "user_data": {"document_id": "INV-2026-00492"}
  }'

{
  "tag": "9e6b2b4a4b9443e6a3a1c7146a0b91f8",
  "status": "queued",
  "status_code": 1,
  "compression_level": "standard",
  "status_url": "https://api.beaglepdf.com/v1/compressions/…"
}

Authentication

All endpoints except health require an active Developer or Enterprise API key. Send it as a Bearer token from your server; do not place it in browser JavaScript or a mobile app.

Authorization: Bearer bgp_live_your_key_here

API keys are shown once when created. BeaglePDF stores a cryptographic hash of the full key, and a revoked key immediately receives 401 Unauthorized.

Create a compression

Use an Idempotency-Key header for every create request. A repeat of the same request returns the original result; reuse with different JSON returns 409 Conflict.

Check status and download

Only the account that created a job can read it. A successful job has status_code: 3 and status: "success".

curl --fail-with-body \
  -H 'Authorization: Bearer bgp_live_REPLACE_ME' \
  'https://api.beaglepdf.com/v1/compressions/TAG_FROM_CREATE'

The download endpoint returns a fresh, short-lived pre-signed URL after success. It never exposes an S3 object key. Before completion it returns 409; after retention expires it returns 410.

Completion webhooks

When you provide callback_url, BeaglePDF sends one webhook after the job succeeds or fails. Deliveries are at least once: handle duplicate webhook_id values safely.

POST https://your-app.example/webhooks/beaglepdf
Content-Type: application/json
BeaglePDF-Timestamp: 1760000000
BeaglePDF-Signature: sha256=<hex digest>

{
  "webhook_id": "wh_…",
  "event": "compression.completed",
  "tag": "…",
  "status": "success",
  "status_code": 3,
  "download_url_endpoint": "https://api.beaglepdf.com/v1/compressions/…/download",
  "user_data": {"document_id": "INV-2026-00492"}
}

Verify the exact raw request body using your webhook signing secret:

HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)

Return any 2xx response to acknowledge delivery. BeaglePDF retries failed deliveries after 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, and 24 hours.

Compression levels

BeaglePDF controls the underlying QPDF configuration. The API does not accept arbitrary command-line options.

Errors, states, and limits

Terminal job states include success and source_download_failed, invalid_pdf, compression_failed, or storage_failed.

Source URL safety

For the protection of your infrastructure and ours, source and callback URLs must use public HTTPS on port 443. BeaglePDF rejects local addresses, private address ranges, link-local addresses, AWS metadata addresses, embedded URL credentials, and hosts with non-public DNS answers.

Source downloads are performed after the job is queued. Redirects are revalidated and the worker pins the vetted destination IP while validating TLS for the original hostname, which helps protect against DNS rebinding. Keep source URLs available until the job completes.

Need help with integration, volume planning, or a private deployment? Contact BeaglePDF.