GentlePDF API Documentation
Integrate robust PDF merging, compression, OCR, and conversion directly into your application.
Base URL & Quickstart
All requests to the GentlePDF REST API should be sent over HTTPS. The root endpoint responds to health checks:
Authentication
Authenticate your API requests by including your secret API key in the x-api-key request header.
x-api-key: gpdf_live_9f81a7b63e2c04...
Status & Error Codes
GentlePDF uses standard HTTP status codes. Errors include a JSON response with a human-readable detail message.
| Status Code | Description |
|---|---|
| 200 OK | The operation completed successfully. Result returned in body. |
| 400 Bad Request | Invalid arguments, corrupt PDF, or missing required fields. |
| 401 Unauthorized | Missing or invalid "x-api-key" header. |
| 402 Payment Required | Insufficient credits remaining. Refill at /api-pricing. |
| 413 Payload Too Large | File exceeds maximum upload size for current credit pack. |
| 429 Too Many Requests | Exceeded rate limit (requests per minute). |
| 500 Server Error | Internal processing failure. Automatic retry recommended. |
Endpoint Reference
Combines two or more PDF files into a single continuous PDF document in the specified order.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| files | multipart/form-data (File[]) | Yes | Two or more PDF files to merge into one. |
import requests
url = "https://api.gentlepdf.com/merge-pdf"
headers = {"x-api-key": "YOUR_API_KEY"}
files = [
("files", open("document1.pdf", "rb")),
("files", open("document2.pdf", "rb"))
]
response = requests.post(url, headers=headers, files=files)
if response.status_code == 200:
with open("merged.pdf", "wb") as f:
f.write(response.content)
print("PDFs merged successfully!")
else:
print(f"Error {response.status_code}: {response.text}")Response Preview
Returns binary application/pdf data containing the merged file.
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="merged.pdf"
[Binary PDF stream]Reduces PDF file size by compressing internal embedded images, streams, and optimizing fonts with multiple quality presets.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | multipart/form-data (File) | Yes | The PDF file to compress. |
| quality | string | Optional | Compression level: "screen" (max reduction, 72 dpi), "ebook" (recommended, 150 dpi), "printer" (300 dpi), "prepress" (color-preserving). Default: "screen". |
import requests
url = "https://api.gentlepdf.com/compress-pdf"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("document.pdf", "rb")}
data = {"quality": "ebook"}
response = requests.post(url, headers=headers, files=files, data=data)
with open("compressed.pdf", "wb") as f:
f.write(response.content)Response Preview
Returns binary application/pdf data containing the optimized and compressed document.
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="compressed.pdf"
[Binary compressed PDF stream]Extract specific page ranges (e.g. "1-3, 5, 8-10") or individual pages into separate PDFs or a single combined PDF.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | multipart/form-data (File) | Yes | The PDF file to split. |
| ranges | string | Yes | Comma-separated page ranges, e.g. "1-2, 4, 6-8". |
| merge | boolean (query param) | Optional | If true, returns a single merged PDF. If false (default), returns a ZIP archive of extracted pages. |
import requests
url = "https://api.gentlepdf.com/split-pdf?merge=true"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("source.pdf", "rb")}
data = {"ranges": "1-3, 5"}
response = requests.post(url, headers=headers, files=files, data=data)
with open("split_result.pdf", "wb") as f:
f.write(response.content)Response Preview
Returns application/pdf (if merge=true) or application/zip (if merge=false).
HTTP 200 OK
Content-Type: application/pdf
[Binary PDF stream]Converts a PDF into an editable Microsoft Word (.docx) document while preserving typography, headings, tables, and images.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | multipart/form-data (File) | Yes | The PDF file to convert to Word. |
import requests
url = "https://api.gentlepdf.com/pdf-to-word"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("contract.pdf", "rb")}
response = requests.post(url, headers=headers, files=files)
with open("contract.docx", "wb") as f:
f.write(response.content)Response Preview
Returns binary application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx).
HTTP 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="document.docx"Scans image-based PDFs or scanned images to recognize embedded text and output searchable text or searchable PDF.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | multipart/form-data (File) | Yes | The scanned PDF or image (PNG/JPEG) to process. |
| language | string | Optional | OCR language code (e.g. "eng", "spa", "fra", "deu"). Default: "eng". |
import requests
url = "https://api.gentlepdf.com/ocr-pdf"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("scanned_receipt.pdf", "rb")}
data = {"language": "eng"}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())Response Preview
Returns JSON containing recognized text per page or binary searchable PDF.
{
"status": "success",
"pages_processed": 1,
"text": "INVOICE #94821\nDate: Oct 14, 2026\nTotal: $120.00"
}Encrypts a PDF using standard 128-bit or 256-bit AES encryption and sets a mandatory user password.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| file | multipart/form-data (File) | Yes | The PDF to password-protect. |
| password | string | Yes | The secret passphrase required to open the PDF. |
import requests
url = "https://api.gentlepdf.com/protect-pdf"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("confidential.pdf", "rb")}
data = {"password": "MySecurePassword123!"}
response = requests.post(url, headers=headers, files=files, data=data)
with open("protected.pdf", "wb") as f:
f.write(response.content)Response Preview
Returns binary application/pdf data containing the encrypted file.
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="protected.pdf"