Post-Processing

Transform existing PDFs with merge, split, compress, password protection, PDF/A conversion, and metadata extraction.

Endpoints

Method	Endpoint	Description
POST	`/v1/pdf/merge`	Merge multiple PDFs
POST	`/v1/pdf/split`	Split PDF into pages
POST	`/v1/pdf/compress`	Compress PDF file size
POST	`/v1/pdf/protect`	Add password protection
POST	`/v1/pdf/pdfa`	Convert to PDF/A format
POST	`/v1/pdf/info`	Extract metadata and info

Merge PDFs

Combine multiple PDF files into a single document.

POST /v1/pdf/merge

Request Body

{
  "pdfs": [
    {
      "source": "base64",
      "data": "JVBERi0xLjQKJeLjz9MK..."
    },
    {
      "source": "url",
      "url": "https://example.com/document.pdf"
    },
    {
      "source": "file_id",
      "file_id": "file_abc123"
    }
  ],
  "options": {
    "add_bookmarks": true,
    "bookmark_titles": ["Cover Page", "Main Content", "Appendix"]
  }
}

Parameters

Parameter	Type	Required	Description
`pdfs`	array	Yes	Array of PDF sources (2-50 files)
`pdfs[].source`	string	Yes	Source type: `base64`, `url`, `file_id`
`pdfs[].data`	string	Conditional	Base64-encoded PDF (if source=base64)
`pdfs[].url`	string	Conditional	PDF URL (if source=url)
`pdfs[].file_id`	string	Conditional	Stored file ID (if source=file_id)
`options.add_bookmarks`	boolean	No	Add bookmarks for each source PDF
`options.bookmark_titles`	array	No	Custom bookmark titles

Response

{
  "success": true,
  "data": {
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "total_pages": 15,
    "file_size": 245678,
    "processing_time_ms": 321
  }
}

Example

import requests
import base64

def merge_pdfs(pdf_files):
    # Read PDF files
    pdfs = []
    for file_path in pdf_files:
        with open(file_path, "rb") as f:
            pdf_data = base64.b64encode(f.read()).decode()
            pdfs.append({
                "source": "base64",
                "data": pdf_data
            })

    response = requests.post(
        "https://lightningpdf.dev/api/v1/pdf/merge",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "pdfs": pdfs,
            "options": {
                "add_bookmarks": True
            }
        }
    )

    result = response.json()
    if result["success"]:
        merged_pdf = base64.b64decode(result["data"]["pdf"])
        return merged_pdf
    else:
        raise Exception(result["error"]["message"])

# Usage
merged = merge_pdfs(["invoice.pdf", "receipt.pdf", "summary.pdf"])
with open("merged.pdf", "wb") as f:
    f.write(merged)

Split PDF

Split a PDF into individual pages or page ranges.

POST /v1/pdf/split

Request Body

{
  "pdf": "JVBERi0xLjQKJeLjz9MK...",
  "mode": "pages",
  "ranges": [
    {"start": 1, "end": 3},
    {"start": 5, "end": 7}
  ]
}

Parameters

Parameter	Type	Required	Description
`pdf`	string	Yes	Base64-encoded PDF
`mode`	string	Yes	Split mode: `pages` (individual), `ranges`
`ranges`	array	Conditional	Page ranges (required if mode=ranges)

Response

{
  "success": true,
  "data": {
    "parts": [
      {
        "pages": "1-3",
        "pdf": "JVBERi0xLjQKJeLjz9MK...",
        "file_size": 34567
      },
      {
        "pages": "5-7",
        "pdf": "JVBERi0xLjQKJeLjz9MK...",
        "file_size": 45678
      }
    ],
    "processing_time_ms": 245
  }
}

Example: Split into Individual Pages

curl -X POST https://lightningpdf.dev/api/v1/pdf/split \
  -H "Authorization: Bearer lpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "mode": "pages"
  }'

Compress PDF

Reduce PDF file size with optimized compression.

POST /v1/pdf/compress

Request Body

{
  "pdf": "JVBERi0xLjQKJeLjz9MK...",
  "level": "medium",
  "options": {
    "downsample_images": true,
    "image_quality": 80,
    "remove_metadata": false
  }
}

Parameters

Parameter	Type	Required	Description
`pdf`	string	Yes	Base64-encoded PDF
`level`	string	No	Compression level: `low`, `medium`, `high`, `extreme`
`options.downsample_images`	boolean	No	Downsample images (default: true)
`options.image_quality`	integer	No	Image quality 1-100 (default: 80)
`options.remove_metadata`	boolean	No	Remove metadata (default: false)

Response

{
  "success": true,
  "data": {
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "original_size": 2456789,
    "compressed_size": 456789,
    "compression_ratio": 81.4,
    "processing_time_ms": 567
  }
}

Example

def compress_pdf(pdf_path, level="medium"):
    with open(pdf_path, "rb") as f:
        pdf_data = base64.b64encode(f.read()).decode()

    response = requests.post(
        "https://lightningpdf.dev/api/v1/pdf/compress",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "pdf": pdf_data,
            "level": level,
            "options": {
                "downsample_images": True,
                "image_quality": 75
            }
        }
    )

    result = response.json()
    if result["success"]:
        print(f"Compressed {result['data']['compression_ratio']}%")
        return base64.b64decode(result["data"]["pdf"])

Password Protection

Add password protection and encryption to PDFs.

POST /v1/pdf/protect

Request Body

{
  "pdf": "JVBERi0xLjQKJeLjz9MK...",
  "user_password": "user123",
  "owner_password": "owner456",
  "permissions": {
    "print": true,
    "modify": false,
    "copy": false,
    "annotations": true
  },
  "encryption": "aes256"
}

Parameters

Parameter	Type	Required	Description
`pdf`	string	Yes	Base64-encoded PDF
`user_password`	string	Yes	Password to open PDF (8-32 chars)
`owner_password`	string	No	Password to change permissions
`permissions`	object	No	Document permissions
`encryption`	string	No	Encryption: `rc4`, `aes128`, `aes256` (default: aes256)

Permissions Object

Permission	Type	Default	Description
`print`	boolean	true	Allow printing
`modify`	boolean	false	Allow modifications
`copy`	boolean	false	Allow copying text
`annotations`	boolean	true	Allow annotations/comments

Response

{
  "success": true,
  "data": {
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "encryption_applied": "aes256",
    "processing_time_ms": 123
  }
}

Example

curl -X POST https://lightningpdf.dev/api/v1/pdf/protect \
  -H "Authorization: Bearer lpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "user_password": "secret123",
    "permissions": {
      "print": true,
      "modify": false,
      "copy": false
    }
  }'

PDF/A Conversion

Convert PDF to archival PDF/A standard for long-term preservation.

POST /v1/pdf/pdfa

Request Body

{
  "pdf": "JVBERi0xLjQKJeLjz9MK...",
  "standard": "PDF/A-1b",
  "options": {
    "embed_fonts": true,
    "convert_colors": true
  }
}

Parameters

Parameter	Type	Required	Description
`pdf`	string	Yes	Base64-encoded PDF
`standard`	string	No	PDF/A standard: `PDF/A-1a`, `PDF/A-1b`, `PDF/A-2b`, `PDF/A-3b` (default: PDF/A-1b)
`options.embed_fonts`	boolean	No	Embed all fonts (default: true)
`options.convert_colors`	boolean	No	Convert to RGB (default: true)

Response

{
  "success": true,
  "data": {
    "pdf": "JVBERi0xLjQKJeLjz9MK...",
    "standard": "PDF/A-1b",
    "validation": {
      "compliant": true,
      "warnings": []
    },
    "processing_time_ms": 456
  }
}

PDF Info & Metadata

Extract metadata, page count, and document information.

POST /v1/pdf/info

Request Body

{
  "pdf": "JVBERi0xLjQKJeLjz9MK..."
}

Response

{
  "success": true,
  "data": {
    "metadata": {
      "title": "Invoice #12345",
      "author": "Acme Corp",
      "subject": "Invoice",
      "creator": "LightningPDF",
      "producer": "Chromium",
      "creation_date": "2024-01-15T10:30:00Z",
      "modification_date": "2024-01-15T10:30:00Z"
    },
    "document": {
      "pages": 3,
      "file_size": 245678,
      "pdf_version": "1.4",
      "encrypted": false,
      "page_size": "Letter (8.5 x 11 in)"
    },
    "fonts": [
      {
        "name": "Helvetica",
        "type": "Type1",
        "embedded": true
      }
    ],
    "permissions": {
      "print": true,
      "modify": true,
      "copy": true,
      "annotations": true
    }
  }
}

Example

def get_pdf_info(pdf_path):
    with open(pdf_path, "rb") as f:
        pdf_data = base64.b64encode(f.read()).decode()

    response = requests.post(
        "https://lightningpdf.dev/api/v1/pdf/info",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={"pdf": pdf_data}
    )

    result = response.json()
    if result["success"]:
        info = result["data"]
        print(f"Pages: {info['document']['pages']}")
        print(f"Size: {info['document']['file_size']} bytes")
        print(f"Encrypted: {info['document']['encrypted']}")
        return info

Complete Example: Invoice Processing Pipeline

import requests
import base64

API_KEY = "lpdf_your_api_key"
BASE_URL = "https://lightningpdf.dev/api/v1"

def process_invoice_pipeline(template_id, invoice_data):
    # 1. Generate invoice PDF
    generate_response = requests.post(
        f"{BASE_URL}/pdf/generate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "template_id": template_id,
            "variables": invoice_data
        }
    )

    pdf_data = generate_response.json()["data"]["pdf"]

    # 2. Convert to PDF/A for archival
    pdfa_response = requests.post(
        f"{BASE_URL}/pdf/pdfa",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "pdf": pdf_data,
            "standard": "PDF/A-1b"
        }
    )

    pdf_data = pdfa_response.json()["data"]["pdf"]

    # 3. Add password protection
    protect_response = requests.post(
        f"{BASE_URL}/pdf/protect",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "pdf": pdf_data,
            "user_password": invoice_data["password"],
            "permissions": {
                "print": True,
                "modify": False,
                "copy": False
            }
        }
    )

    final_pdf = protect_response.json()["data"]["pdf"]

    # 4. Save final PDF
    pdf_bytes = base64.b64decode(final_pdf)
    filename = f"invoice_{invoice_data['invoice_number']}.pdf"
    with open(filename, "wb") as f:
        f.write(pdf_bytes)

    print(f"Invoice processed and saved: {filename}")
    return pdf_bytes

# Usage
invoice_data = {
    "invoice_number": "INV-2024-001",
    "customer_name": "Acme Corp",
    "total": 542.50,
    "password": "acme123"
}

process_invoice_pipeline("tpl_abc123", invoice_data)

Error Codes

Code	Description
`invalid_pdf`	PDF file is corrupted or invalid
`pdf_encrypted`	Cannot process encrypted PDF without password
`invalid_ranges`	Page ranges are out of bounds
`compression_failed`	Compression could not be applied
`pdfa_conversion_failed`	PDF/A conversion failed (non-compliant source)

Credit Usage

Post-processing operations consume credits:

Merge: 1 credit per output PDF
Split: 1 credit per output part
Compress: 1 credit
Protect: 1 credit
PDF/A: 1 credit
Info: Free (no credit)