Reference

Compress PDF

Compression keeps the existing multipart upload contract while normalizing auth, idempotency, status polling, and downloads through the public DocuShell API host.

Reference

View as Markdown

Getting startedShared headers, queued jobs, and request IDs.OverviewSee the full endpoint inventory.

Reference

Endpoint Reference

POST/v1/pdf/compress

Queue a PDF compression job using the existing multipart browser-lane contract behind the public API gateway.

Auth

Bearer token required.

Idempotency

Supports optional Idempotency-Key replay protection and file-hash-aware retries.

Content Type

multipart/form-data

Headers

Name	Type	Required	Location	Description
Authorization	Bearer <API_KEY>	Yes	header	User-owned API key created in the DocuShell dashboard.
Idempotency-Key	string	No	header	Recommended for safely retrying submit requests without creating duplicate jobs.
X-File-Name	string	No	header	Optional file name hint used for idempotency hashing and job metadata.
X-File-Size	integer	No	header	Optional caller-declared byte size used for sizing and idempotency hashing.
X-File-SHA256	string	No	header	Optional digest used to make retries safer when the same payload is sent again.

Request Fields

Name	Type	Required	Location	Description
files	file[]	Yes	multipart	One or more PDF uploads using the existing browser-lane form field.
mode	basic \| strong \| custom	No	multipart	Compression mode.
dpi	integer	No	multipart	Custom output DPI for `custom` mode. Supported range is 72 to 300.
quality	integer	No	multipart	Custom JPEG quality for `custom` mode. Supported range is 10 to 100.
grayscale	boolean	No	multipart	Produce grayscale output.
linearize	boolean	No	multipart	Optimize the PDF for fast web viewing (linearization).

Upload and compress

bash

curl -X POST "https://api.docushell.com/api/v1/pdf/compress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: compress-demo-001" \
  -H "X-File-Name: annual-report.pdf" \
  -F "files=@./annual-report.pdf;type=application/pdf" \
  -F "mode=strong" \
  -F "linearize=true"

Try It Now

Console placeholder for safe sandbox execution.

Coming soon

MethodEndpointHeadersRequest Body

{
  "example": "Paste a request body when the sandbox is enabled"
}

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 5,
  "service": "compress-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Status response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "compress-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quarterly-report.pdf",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "completed_at": "2026-04-24T10:12:56.145Z",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Completed jobs return a public download link and keep the file streaming URL behind the gateway. Downloads use application/pdf.

Poll And Download

Completed jobs stream the compressed application/pdf from GET /v1/jobs/:jobId/download.
See [Quickstart](/getting-started#queued-response) for the shared submit, poll, and download flow.

Failure Notes

Uploads larger than 1 GB are rejected before the job is recorded.
Invalid PDFs and encrypted PDFs are rejected by the compression service during validation.
backend_unavailable covers temporary compression service outages before the queue handoff succeeds.

Upload too large

400invalid_request

The public route enforces a hard 1 GB ceiling on streamed uploads.

400 error

json

{
  "error": {
    "code": "invalid_request",
    "message": "Upload exceeds maximum allowed size (1 GB).",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Code Samples

Upload and compress

curl -X POST "https://api.docushell.com/api/v1/pdf/compress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: compress-demo-001" \
  -H "X-File-Name: annual-report.pdf" \
  -F "files=@./annual-report.pdf;type=application/pdf" \
  -F "mode=strong" \
  -F "linearize=true"

Queued response

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 5,
  "service": "compress-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}