> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Compress Document
> Compress a PDF document to reduce its file size and return a temporary download URL.
This endpoint requires the following scope:
`pdf:files`
## OpenAPI
````yaml tabs/api-reference/lumin-openapi.yaml POST /documents/compress
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/documents/compress:
post:
tags:
- Documents
summary: Compress Document
description: >
Compress a PDF document to reduce its file size and return a temporary
download URL.
The document can be specified by a Lumin document ID or by a publicly
accessible file URL.
The compressed file is **temporary** — the `signed_url` expires after 30
minutes. To persist the result, download the file and re-upload it via
[Create Document](/tabs/api-reference/api/documents/create-document).
**Supported file type:** PDF only.
**Plan restrictions:**
- **Pro / Business** plans: compress files up to 500 MB; access to both
`standard` and `maximum` compression levels.
- **Other plans:** compress files up to 20 MB; `standard` compression
level only.
**Absolute file size limit:** 500 MB regardless of plan.
Password-protected documents cannot be compressed.
**File URL restrictions:** Only URLs from allowed domains are accepted
(`api.luminpdf.com`, `*.s3.amazonaws.com`, `*.s3.*.amazonaws.com`).
Redirecting URLs are not supported.
**Input priority:** If both `document_id` and `file_url` are provided,
`document_id` takes priority and `file_url` is ignored.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentCompressRequest'
examples:
standard:
summary: Standard compression
value:
document_id: 695dd6880d951f4de70a7c5d
compression_level: standard
maximum:
summary: Maximum compression with options
value:
document_id: 695dd6880d951f4de70a7c5d
compression_level: maximum
document_name: NDA Compressed
options:
image_dpi: 72
embed_fonts: true
subset_fonts: true
remove_annotations: true
remove_metadata: false
responses:
'200':
description: Returns a temporary download URL for the compressed PDF.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentOperationResponse'
example:
document_name: NDA Compressed_compressed
signed_url: >-
https://files.luminpdf.com/download/compressed-abc123?token=xyz789
expires_at: 1755526530000
application/pdf:
schema:
type: string
format: binary
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- pdf:files
components:
schemas:
DocumentCompressRequest:
type: object
required:
- compression_level
properties:
document_id:
type: string
description: >
Lumin document ID of the PDF to compress.
Required when `file_url` is not provided. Takes priority if both are
provided.
To obtain a document ID, upload the file to Lumin first using
[Upload
Document](/tabs/api-reference/api/documents/create-document).
file_url:
type: string
format: uri
description: >
Publicly accessible URL of the PDF file to compress.
Required when `document_id` is not provided. Ignored if
`document_id` is also provided.
compression_level:
type: string
enum:
- standard
- maximum
description: >
Compression level.
- `standard` — ~150 dpi images, removes non-essential bookmarks and
unused metadata. Targets ≥ 30% file size reduction.
- `maximum` — ~72–96 dpi images, strips all non-essential content.
Targets ≥ 60% file size reduction. Requires Pro / Business plan.
document_name:
type: string
minLength: 1
maxLength: 255
description: >-
Name of the compressed output file. Defaults to
`compressed_{original document name}`.
options:
$ref: '#/components/schemas/DocumentCompressOptions'
DocumentOperationResponse:
type: object
required:
- document_name
- signed_url
- expires_at
properties:
document_name:
type: string
description: Name of the output document.
signed_url:
type: string
format: uri
description: >-
Temporary HTTPS URL to download the output file. Expires after 30
minutes.
expires_at:
type: integer
format: unix-epoch
description: >-
Unix epoch timestamp (in milliseconds) when `signed_url` becomes
invalid.
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
DocumentCompressOptions:
type: object
description: >-
Advanced compression settings. Only applicable when `compression_level`
is `maximum`.
properties:
image_dpi:
type: integer
minimum: 72
maximum: 300
default: 96
description: >-
Target resolution for downsampled color images. Lower values produce
smaller files.
embed_fonts:
type: boolean
default: true
description: Keep fonts embedded in the file so it renders consistently.
subset_fonts:
type: boolean
default: true
description: >-
Only include characters actually used in the document. Only applies
when `embed_fonts` is `true`.
remove_annotations:
type: boolean
default: false
description: Remove all annotations (comments, highlights, etc.) from the file.
remove_metadata:
type: boolean
default: false
description: Remove outlines, bookmarks, and document info metadata.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````