Merge multiple PDF documents into a single PDF file. This endpoint combines PDFs in the order they are provided, appending each document sequentially.

Endpoint

POST /mergePdfs

Authentication

Requires a valid API key or OAuth token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Request Body

Content-Type: application/json or multipart/form-data

Note: You must provide at least one of pdfs_base64, pdfs_url (for JSON requests), or files (for multipart requests). pdfs_base64 and pdfs_url can be combined — base64 PDFs are processed first, then URL PDFs, all appended sequentially.

Field Details

pdfs_base64 (conditional, JSON only)

An array of base64-encoded PDF files. Each string in the array should be a complete PDF file encoded in base64. The encoded strings should not include the data URI prefix.

Example array structure:

{
  "pdfs_base64": [
    "JVBERi0xLjcK...",  // First PDF (base64)
    "JVBERi0xLjQK...",  // Second PDF (base64)
    "JVBERi0xLjUK..."   // Third PDF (base64)
  ]
}

pdfs_url (conditional, JSON only)

An array of URLs pointing to PDF files. Each URL is fetched server-side (follows redirects). URLs are validated against SSRF before fetching.

Example array structure:

{
  "pdfs_url": [
    "https://example.com/cover.pdf",
    "https://example.com/chapter1.pdf",
    "https://example.com/appendix.pdf"
  ]
}

files (conditional, multipart only)

Multiple PDF file uploads via multipart form data. Each file should be a valid PDF document. Files are merged in the order they are received.

filename (optional)

The filename for the output merged PDF. Defaults to “merged.pdf”. The .pdf extension is automatically added if not provided.

Storage Options

Control how the merged PDF is stored and returned.

Storage Modes:

• memory: Return PDF bytes directly in response (no persistence). This is the default for REST API calls.
• default: Store in pdf-mcp S3 bucket, return JSON with document metadata and signed URL.
• byob: Store in your own S3 bucket (requires BYOB configuration).

Example Request

Merge PDFs Using Base64 (JSON)

# First, encode your PDFs to base64
PDF1_BASE64=$(base64 -i document1.pdf)
PDF2_BASE64=$(base64 -i document2.pdf)
PDF3_BASE64=$(base64 -i document3.pdf)

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs_base64": ["'"$PDF1_BASE64"'", "'"$PDF2_BASE64"'", "'"$PDF3_BASE64"'"],
    "filename": "combined-document.pdf"
  }' \
  --output combined-document.pdf

Merge Two PDFs (JSON)

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs_base64": ["'"$(base64 -i cover.pdf)"'", "'"$(base64 -i content.pdf)"'"]
  }' \
  --output merged.pdf

Merge PDFs from URLs

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs_url": [
      "https://example.com/cover.pdf",
      "https://example.com/chapter1.pdf",
      "https://example.com/appendix.pdf"
    ],
    "filename": "combined-document.pdf"
  }' \
  --output combined-document.pdf

Mix Base64 and URLs

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs_base64": ["'"$(base64 -i cover.pdf)"'"],
    "pdfs_url": ["https://example.com/chapter1.pdf"],
    "filename": "mixed-sources.pdf"
  }' \
  --output mixed-sources.pdf

Using File Upload (Multipart)

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@document1.pdf" \
  -F "files=@document2.pdf" \
  -F "files=@document3.pdf" \
  --output merged.pdf

File Upload with Custom Filename

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@chapter1.pdf" \
  -F "files=@chapter2.pdf" \
  -F "files=@chapter3.pdf" \
  -F "filename=complete-book.pdf" \
  --output complete-book.pdf

With Storage (Persistent PDF)

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs_base64": ["'"$(base64 -i cover.pdf)"'", "'"$(base64 -i content.pdf)"'"],
    "filename": "complete-document.pdf",
    "storage": {
      "mode": "default",
      "filename": "complete-document.pdf",
      "expires_in": 86400,
      "retention_days": 30
    }
  }'

Response

Success (memory mode)

When storage.mode is memory or not provided, returns the merged PDF as a binary file download.

Response Headers:

Success (with storage)

When storage.mode is default or byob, returns JSON with document metadata and a signed download URL:

{
  "success": true,
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://s3.eu-central-1.amazonaws.com/...",
  "filename": "complete-document.pdf",
  "file_size_bytes": 125678,
  "page_count": 15,
  "storage_mode": "default",
  "expires_at": "2024-02-15T10:30:00Z",
  "signed_url_expires_at": "2024-01-15T12:00:00Z"
}

Error

{
  "error": "Failed to merge PDFs",
  "message": "Error description"
}

Status Codes:

How Merging Works

Merge Process

The API uses PyPDF to combine PDF documents:

1. Each input PDF is validated and parsed
2. PDFs are appended in the exact order provided
3. All pages from the first PDF are added, then all pages from the second, and so on
4. The merged document is returned as a single PDF file

Preservation

When merging PDFs, the following are preserved:

• Page dimensions and orientations
• Text content and formatting
• Images and graphics
• Internal links within each original document

Considerations

• Page numbering is recalculated for the merged document
• Cross-document links are not automatically updated
• Bookmarks/outlines from source PDFs may need manual handling

Use Cases

Combine Report Sections

Merge separately generated sections into a complete report:

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@cover-page.pdf" \
  -F "files=@table-of-contents.pdf" \
  -F "files=@executive-summary.pdf" \
  -F "files=@main-content.pdf" \
  -F "files=@appendices.pdf" \
  -F "filename=annual-report-2024.pdf" \
  --output annual-report-2024.pdf

Assemble Invoice Package

Combine invoice with supporting documents:

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@invoice.pdf" \
  -F "files=@receipt.pdf" \
  -F "files=@terms-and-conditions.pdf" \
  -F "filename=invoice-package.pdf" \
  --output invoice-package.pdf

Combine Scanned Documents

Merge multiple scanned pages into a single document:

curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@scan-page1.pdf" \
  -F "files=@scan-page2.pdf" \
  -F "files=@scan-page3.pdf" \
  -F "filename=complete-scan.pdf" \
  --output complete-scan.pdf

Build Custom Document from Extracted Pages

Combine with Extract Pages to build custom documents:

# Step 1: Extract specific pages from source documents
# (Creates extracted-from-doc1.pdf and extracted-from-doc2.pdf)

# Step 2: Merge the extracted pages
curl -X POST https://api.pdf-mcp.io/mergePdfs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@extracted-from-doc1.pdf" \
  -F "files=@extracted-from-doc2.pdf" \
  -F "filename=custom-compilation.pdf" \
  --output custom-compilation.pdf

Tips and Best Practices

Choosing Input Method

• URL (JSON): Best for PDFs already hosted online — no download or encoding needed
• File upload (multipart): Simplest option for local files; no encoding required
• Base64 (JSON): Best for programmatic access when PDFs are already in memory or coming from other API calls
• Mixed: Combine pdfs_base64 and pdfs_url in a single request to merge from multiple sources

File Order

PDFs are merged in the exact order provided:

• For multipart: Order of -F "files=@..." parameters
• For JSON: Order of items in the pdfs_base64 array

Plan your file order carefully to ensure the correct document structure.

Performance Optimization

• Keep the number of files reasonable (merging 100+ files may be slow)
• For very large documents, consider merging in batches
• Use file upload when possible to avoid base64 encoding overhead

Error Handling

• Validate each PDF before merging to identify problematic files
• If merge fails, try merging files one at a time to identify the corrupted file
• Ensure all input files are valid PDFs (not images or other formats)

Common Patterns

# Merge two documents
-F "files=@doc1.pdf" -F "files=@doc2.pdf"

# Add cover page to existing document
-F "files=@cover.pdf" -F "files=@main.pdf"

# Append appendix to document
-F "files=@main.pdf" -F "files=@appendix.pdf"

# Combine multiple chapters
-F "files=@ch1.pdf" -F "files=@ch2.pdf" -F "files=@ch3.pdf"

Related Endpoints

• Extract Pages - Extract specific pages before merging
• HTML to PDF - Generate PDFs to merge
• Page Count - Check page counts before merging

Credit Usage

Approximately 0.5 credits per page in the merged output PDF.