POST/api/v1/pdf/merge

Merge PDFs

Combine two or more PDF files into a single document. Files are merged in the order they are uploaded. Supports optional blank page insertion between documents and output optimization for smaller file sizes.

Content-Type: multipart/form-data

Parameters

Parameter	Type	Required	Default	Description
`files`	file[]	Required	-	Two or more PDF files to merge. Files are combined in upload order.
`add_blank_pages`	boolean	Optional	`false`	Insert a blank page between each merged document. Useful for duplex printing.
`optimize_output`	boolean	Optional	`true`	Optimize the merged PDF for smaller file size by deduplicating shared resources.

Code Examples

cURL

bash

curl -X POST "https://app.alternapdf.com/api/v1/pdf/merge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@chapter1.pdf" \
  -F "files=@chapter2.pdf" \
  -F "files=@chapter3.pdf" \
  -F "add_blank_pages=false" \
  -F "optimize_output=true" \
  --output merged.pdf

Python

python

import requests

url = "https://app.alternapdf.com/api/v1/pdf/merge"
headers = {"X-API-Key": "YOUR_API_KEY"}

files = [
    ("files", ("chapter1.pdf", open("chapter1.pdf", "rb"), "application/pdf")),
    ("files", ("chapter2.pdf", open("chapter2.pdf", "rb"), "application/pdf")),
    ("files", ("chapter3.pdf", open("chapter3.pdf", "rb"), "application/pdf")),
]

data = {
    "add_blank_pages": "false",
    "optimize_output": "true",
}

response = requests.post(url, headers=headers, files=files, data=data)

with open("merged.pdf", "wb") as f:
    f.write(response.content)

print(f"Merged PDF saved ({len(response.content)} bytes)")

JavaScript

javascript

const fs = require("fs");
const FormData = require("form-data");
const axios = require("axios");

const form = new FormData();
form.append("files", fs.createReadStream("chapter1.pdf"));
form.append("files", fs.createReadStream("chapter2.pdf"));
form.append("files", fs.createReadStream("chapter3.pdf"));
form.append("add_blank_pages", "false");
form.append("optimize_output", "true");

const response = await axios.post(
  "https://app.alternapdf.com/api/v1/pdf/merge",
  form,
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      ...form.getHeaders(),
    },
    responseType: "arraybuffer",
  }
);

fs.writeFileSync("merged.pdf", response.data);
console.log(`Merged PDF saved (${response.data.byteLength} bytes)`);

Response

200Merged PDF binary

Header	Value
`Content-Type`	application/pdf
`Content-Disposition`	attachment; filename="merged.pdf"

The response body contains the raw PDF binary. Save it directly to a file. On error, a JSON object with a detail field is returned instead.