REST API Reference • v1.0

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:

https://api.gentlepdf.comProduction Endpoint

Authentication

Authenticate your API requests by including your secret API key in the x-api-key request header.

# Pass header with every call:
x-api-key: gpdf_live_9f81a7b63e2c04...
Keep your API key secret! Never commit your key to public GitHub repositories or expose it in client-side frontends.

Status & Error Codes

GentlePDF uses standard HTTP status codes. Errors include a JSON response with a human-readable detail message.

Status CodeDescription
200 OKThe operation completed successfully. Result returned in body.
400 Bad RequestInvalid arguments, corrupt PDF, or missing required fields.
401 UnauthorizedMissing or invalid "x-api-key" header.
402 Payment RequiredInsufficient credits remaining. Refill at /api-pricing.
413 Payload Too LargeFile exceeds maximum upload size for current credit pack.
429 Too Many RequestsExceeded rate limit (requests per minute).
500 Server ErrorInternal processing failure. Automatic retry recommended.

Endpoint Reference

POST/merge-pdf
Cost:1 Credit

Combines two or more PDF files into a single continuous PDF document in the specified order.

Request Parameters

FieldTypeRequiredDescription
filesmultipart/form-data (File[])YesTwo or more PDF files to merge into one.
Example Request (Python)
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]
POST/compress-pdf
Cost:1 Credit

Reduces PDF file size by compressing internal embedded images, streams, and optimizing fonts with multiple quality presets.

Request Parameters

FieldTypeRequiredDescription
filemultipart/form-data (File)YesThe PDF file to compress.
qualitystringOptionalCompression level: "screen" (max reduction, 72 dpi), "ebook" (recommended, 150 dpi), "printer" (300 dpi), "prepress" (color-preserving). Default: "screen".
Example Request (Python)
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]
POST/split-pdf
Cost:1 Credit

Extract specific page ranges (e.g. "1-3, 5, 8-10") or individual pages into separate PDFs or a single combined PDF.

Request Parameters

FieldTypeRequiredDescription
filemultipart/form-data (File)YesThe PDF file to split.
rangesstringYesComma-separated page ranges, e.g. "1-2, 4, 6-8".
mergeboolean (query param)OptionalIf true, returns a single merged PDF. If false (default), returns a ZIP archive of extracted pages.
Example Request (Python)
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]
POST/pdf-to-word
Cost:2 Credits

Converts a PDF into an editable Microsoft Word (.docx) document while preserving typography, headings, tables, and images.

Request Parameters

FieldTypeRequiredDescription
filemultipart/form-data (File)YesThe PDF file to convert to Word.
Example Request (Python)
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"
POST/ocr-pdf
Cost:3 Credits

Scans image-based PDFs or scanned images to recognize embedded text and output searchable text or searchable PDF.

Request Parameters

FieldTypeRequiredDescription
filemultipart/form-data (File)YesThe scanned PDF or image (PNG/JPEG) to process.
languagestringOptionalOCR language code (e.g. "eng", "spa", "fra", "deu"). Default: "eng".
Example Request (Python)
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"
}
POST/protect-pdf
Cost:1 Credit

Encrypts a PDF using standard 128-bit or 256-bit AES encryption and sets a mandatory user password.

Request Parameters

FieldTypeRequiredDescription
filemultipart/form-data (File)YesThe PDF to password-protect.
passwordstringYesThe secret passphrase required to open the PDF.
Example Request (Python)
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"