Bytefusedocs
Subscribe

Compress

Compress PDF

Compress a single PDF and get back a public download URL. The call is synchronous — the file is already compressed and stored by the time you get the response.

Free to try — no key required 20 credits / callSynchronous

Overview

Send a Base64-encoded PDF as JSON; receive an R2 download URL for the compressed file, valid for 24 hours. This endpoint is on the free-try path — call it with no credentials to evaluate it (anonymous calls are metered at 0 credits and rate-limited by IP).

POSThttps://api.bytefuse.in/api/v1/compression/single

Request

Content type application/json. The body is a CompressionRequest:

file_datastringrequired
Base64-encoded PDF bytes (no data: prefix). Must be at least 100 characters; invalid Base64 returns 400.
filenamestringrequired
Original filename. Must end in .pdf (case-insensitive) or the request is rejected with 422.
optionsobjectoptional
A CompressionOptions object (preserve_metadata, preserve_annotations, preserve_forms). Currently accepted but ignored by this endpoint.Default: null

options is not yet wired up

The options object is validated but has no effect on the output today. Don’t rely on it to preserve metadata, annotations or forms.

Compression level

You don’t choose the strength — your plan tier does. The endpoint maps your account type to an engine level:

TierLevelTypical reduction
Freebasic~45%
Promedium~65%
Enterprisemaximum~80–85%

Anonymous calls (no account type) default to medium. Quality preservation is always on.

Response

200 OK, application/json — a CompressionResponse:

200 OK
{
  "compression_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "original_size": 10485760,
  "compressed_size": 4194304,
  "compression_ratio": 0.4,
  "quality_score": 0.95,
  "processing_time_ms": 2500,
  "download_url": "https://<r2-host>/compressed/....pdf",
  "expires_at": "2026-07-05T10:00:00+00:00",
  "tier_power_used": 0.8,
  "could_compress_more": true
}
compression_idstringoptional
A fresh UUID for this call. Not a persisted job id — it won’t resolve on the status endpoint.
statusstringoptional
Always "completed" (the call is synchronous).
original_sizeintoptional
Input size in bytes.
compressed_sizeintoptional
Output size in bytes.
compression_ratiofloatoptional
compressed ÷ original, between 0 and 1 — lower is better.
quality_scorefloatoptional
0–1, higher is better. Defaults to 0.9 if the engine omits it.
processing_time_msintoptional
Engine processing time in milliseconds.
download_urlstringoptional
Public R2 URL of the compressed PDF.
expires_atstringoptional
ISO-8601 UTC expiry — 24 hours after the call.
tier_power_usedfloatoptional
0.6 / 0.8 / 1.0 for basic / medium / maximum.
could_compress_morebooloptional
true unless the level was maximum (i.e. true for everyone below Enterprise).

The response header X-Credits-Charged reports the credits billed — 20 for an authenticated call, 0 for anonymous.

Examples

curl -X POST https://api.bytefuse.in/api/v1/compression/single \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dt_live_your_key" \
  -d '{
    "file_data": "JVBERi0xLjQK...BASE64_PDF...",
    "filename": "report.pdf"
  }'
# Omit the X-API-Key header to use the anonymous free-try path.

Errors

400Base64 decode failed — file_data isn’t valid Base64.
422filename doesn’t end in .pdf, or file_data is under 100 characters.
402Insufficient credits (authenticated calls).
429Rate limited — retry after the Retry-After header.
500The compression engine failed unexpectedly.
503Tool disabled by an admin, or a pricing/billing config error.

Batch compression is not available yet

/compression/batch exists in the API but is currently a stub — it accepts files, does no compression and charges nothing. Use /single per file for now. Full error semantics are on the Errors page.
PreviousErrorsNext Convert Document