Manipulation and Conversion

The PDF Toolkit covers the most common document manipulation workflows. Most routes are GET with query parameters; only merge and protect accept a JSON body.

Core endpoints

Method Endpoint Purpose
POST /v1/pdf/merge Merge 2–20 PDFs into one
GET /v1/pdf/split Split a PDF into parts or individual pages
GET /v1/pdf/rotate Rotate selected pages
GET /v1/pdf/compress Reduce file size
GET /v1/pdf/watermark Add a text watermark
POST /v1/pdf/protect Encrypt or decrypt a PDF
GET /v1/pdf/to-images Render PDF pages as PNG or JPEG

Only merge and protect take a JSON body

split, rotate, compress, watermark, and to-images are GET endpoints with query parameters. Sending them a POST with a JSON payload returns 405 Method Not Allowed.

REST API Examples

Merge PDFs

curl -X POST "https://pdf.toolkitapi.io/v1/pdf/merge" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pdf_urls": ["https://toolkitapi.io/a.pdf", "https://toolkitapi.io/b.pdf", "https://toolkitapi.io/c.pdf"]}'
import base64

import requests

resp = requests.post(
    "https://pdf.toolkitapi.io/v1/pdf/merge",
    headers={"X-API-Key": "YOUR_KEY"},
    json={"pdf_urls": [
        "https://toolkitapi.io/a.pdf",
        "https://toolkitapi.io/b.pdf",
    ]},
    timeout=120,
)
resp.raise_for_status()
data = resp.json()

with open("merged.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf"]))
print(f"Merged {data['input_count']} files into {data['page_count']} pages")
const resp = await fetch("https://pdf.toolkitapi.io/v1/pdf/merge", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    pdf_urls: ["https://toolkitapi.io/a.pdf", "https://toolkitapi.io/b.pdf"],
  }),
});
if (!resp.ok) throw new Error(`merge failed: ${resp.status}`);
const data = await resp.json();
console.log(`Merged PDF: ${data.page_count} pages, ${data.file_size} bytes`);
// data.pdf is a base64 string

Response

{
  "pdf": "JVBERi0xLjQK...",
  "page_count": 12,
  "file_size": 482133,
  "input_count": 2
}

Split a PDF

pages defaults to all, which splits into individual pages. Pass ranges to group pages.

curl -G "https://pdf.toolkitapi.io/v1/pdf/split" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "url=https://toolkitapi.io/report.pdf" \
  --data-urlencode "pages=1-3,5"
import base64

import requests

resp = requests.get(
    "https://pdf.toolkitapi.io/v1/pdf/split",
    params={"url": "https://toolkitapi.io/report.pdf", "pages": "1-3,5"},
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=120,
)
resp.raise_for_status()
data = resp.json()

for i, part in enumerate(data["parts"], start=1):
    with open(f"part-{i}.pdf", "wb") as f:
        f.write(base64.b64decode(part["pdf"]))
print(f"Split into {data['total_parts']} parts from {data['source_page_count']} pages")
const url = new URL("https://pdf.toolkitapi.io/v1/pdf/split");
url.search = new URLSearchParams({
  url: "https://toolkitapi.io/report.pdf",
  pages: "1-3,5",
});

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Produced ${data.total_parts} parts`);

Response

{
  "parts": [{ "pdf": "JVBERi0xLjQK..." }, { "pdf": "JVBERi0xLjQK..." }],
  "total_parts": 2,
  "source_page_count": 10
}

Rotate pages

angle is required and must be 90, 180, or 270 (clockwise). Omit pages to rotate the whole document.

curl -G "https://pdf.toolkitapi.io/v1/pdf/rotate" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "url=https://toolkitapi.io/report.pdf" \
  --data-urlencode "angle=90" \
  --data-urlencode "pages=1-2"
import base64

import requests

resp = requests.get(
    "https://pdf.toolkitapi.io/v1/pdf/rotate",
    params={"url": "https://toolkitapi.io/report.pdf", "angle": 90, "pages": "1-2"},
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=60,
)
resp.raise_for_status()
data = resp.json()

with open("rotated.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf"]))
print(f"Rotated {data['rotated_pages']} of {data['page_count']} pages by {data['angle']}°")
const url = new URL("https://pdf.toolkitapi.io/v1/pdf/rotate");
url.search = new URLSearchParams({ url: "https://toolkitapi.io/report.pdf", angle: "90", pages: "1-2" });

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Rotated ${data.rotated_pages} pages`);

Response

{
  "pdf": "JVBERi0xLjQK...",
  "page_count": 10,
  "rotated_pages": 2,
  "angle": 90,
  "file_size": 204811
}

Compress a PDF

Takes only url — there is no quality or level parameter.

curl -G "https://pdf.toolkitapi.io/v1/pdf/compress" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "url=https://toolkitapi.io/large-report.pdf"
import base64

import requests

resp = requests.get(
    "https://pdf.toolkitapi.io/v1/pdf/compress",
    params={"url": "https://toolkitapi.io/large-report.pdf"},
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=180,
)
resp.raise_for_status()
data = resp.json()

with open("compressed.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf"]))
print(f"{data['original_size']} → {data['compressed_size']} bytes ({data['savings_percent']}% saved)")
const url = new URL("https://pdf.toolkitapi.io/v1/pdf/compress");
url.search = new URLSearchParams({ url: "https://toolkitapi.io/large-report.pdf" });

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Saved ${data.savings_percent}% (${data.page_count} pages)`);

Response

{
  "pdf": "JVBERi0xLjQK...",
  "original_size": 5242880,
  "compressed_size": 1572864,
  "savings_percent": 70.0,
  "page_count": 40
}

Add a text watermark

curl -G "https://pdf.toolkitapi.io/v1/pdf/watermark" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "url=https://toolkitapi.io/report.pdf" \
  --data-urlencode "text=CONFIDENTIAL" \
  --data-urlencode "font_size=48" \
  --data-urlencode "opacity=0.15" \
  --data-urlencode "angle=45" \
  --data-urlencode "pages=1-3"
import base64

import requests

resp = requests.get(
    "https://pdf.toolkitapi.io/v1/pdf/watermark",
    params={
        "url": "https://toolkitapi.io/report.pdf",
        "text": "CONFIDENTIAL",
        "font_size": 48,
        "opacity": 0.15,
        "angle": 45,
        "pages": "1-3",
    },
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=60,
)
resp.raise_for_status()
data = resp.json()

with open("watermarked.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf"]))
print(f"Watermarked {data['watermarked_pages']} of {data['page_count']} pages")
const url = new URL("https://pdf.toolkitapi.io/v1/pdf/watermark");
url.search = new URLSearchParams({
  url: "https://toolkitapi.io/report.pdf",
  text: "CONFIDENTIAL",
  opacity: "0.15",
  angle: "45",
  pages: "1-3",
});

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Watermarked ${data.watermarked_pages} pages`);

Response

{
  "pdf": "JVBERi0xLjQK...",
  "page_count": 10,
  "watermarked_pages": 3,
  "file_size": 312455
}

Encrypt or decrypt a PDF

protect is a POST with a JSON body. action is encrypt or decrypt.

curl -X POST "https://pdf.toolkitapi.io/v1/pdf/protect" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://toolkitapi.io/report.pdf",
    "action": "encrypt",
    "user_password": "open123",
    "owner_password": "owner456"
  }'
import base64

import requests

resp = requests.post(
    "https://pdf.toolkitapi.io/v1/pdf/protect",
    headers={"X-API-Key": "YOUR_KEY"},
    json={
        "url": "https://toolkitapi.io/report.pdf",
        "action": "encrypt",
        "user_password": "open123",
        "owner_password": "owner456",
        "allow_printing": True,
        "allow_copying": False,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()

with open("protected.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf"]))
print(f"{data['action']}: encrypted={data['is_encrypted']}")
const resp = await fetch("https://pdf.toolkitapi.io/v1/pdf/protect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://toolkitapi.io/report.pdf",
    action: "encrypt",
    user_password: "open123",
    owner_password: "owner456",
  }),
});
const data = await resp.json();
console.log(`${data.action}: encrypted=${data.is_encrypted}`);

Response

{
  "pdf": "JVBERi0xLjQK...",
  "action": "encrypt",
  "is_encrypted": true,
  "page_count": 10,
  "file_size": 244900
}

Convert PDF to images

curl -G "https://pdf.toolkitapi.io/v1/pdf/to-images" \
  -H "X-API-Key: YOUR_KEY" \
  --data-urlencode "url=https://toolkitapi.io/report.pdf" \
  --data-urlencode "pages=1-2" \
  --data-urlencode "format=png" \
  --data-urlencode "dpi=150"
import base64

import requests

resp = requests.get(
    "https://pdf.toolkitapi.io/v1/pdf/to-images",
    params={
        "url": "https://toolkitapi.io/report.pdf",
        "pages": "1-2",
        "format": "jpeg",
        "dpi": 200,
    },
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=120,
)
resp.raise_for_status()
data = resp.json()

for i, img in enumerate(data["images"], start=1):
    with open(f"page-{i}.{data['format']}", "wb") as f:
        f.write(base64.b64decode(img["image"]))
print(f"Rendered {data['rendered_pages']} of {data['total_pages']} pages at {data['dpi']} DPI")
const url = new URL("https://pdf.toolkitapi.io/v1/pdf/to-images");
url.search = new URLSearchParams({
  url: "https://toolkitapi.io/report.pdf",
  pages: "1-2",
  format: "jpeg",
  dpi: "200",
});

const resp = await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } });
const data = await resp.json();
console.log(`Rendered ${data.rendered_pages} pages at ${data.dpi} DPI`);

Response

{
  "images": [{ "image": "iVBORw0KGgoAAAANSUhEUg..." }, { "image": "..." }],
  "total_pages": 10,
  "rendered_pages": 2,
  "format": "jpeg",
  "dpi": 200
}

Python SDK Examples

Merge PDFs

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.merge(
        pdf_urls=[
            "https://toolkitapi.io/a.pdf",
            "https://toolkitapi.io/b.pdf",
        ]
    )
    print(result["page_count"])

Split pages

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.split(
        url="https://toolkitapi.io/report.pdf",
        pages="1-3,4-6",
    )
    print(result["total_parts"])

Rotate pages

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.rotate(
        90,
        url="https://toolkitapi.io/report.pdf",
        pages="1-2",
    )
    print(result["rotated_pages"])

Compress a PDF

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.compress(url="https://toolkitapi.io/report.pdf")
    print(result["savings_percent"])

Add a watermark

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.watermark(
        "CONFIDENTIAL",
        url="https://toolkitapi.io/report.pdf",
        opacity=0.12,
        angle=45,
    )
    print(result["watermarked_pages"])

Protect a document

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.protect(
        url="https://toolkitapi.io/report.pdf",
        action="encrypt",
        user_password="open123",
        owner_password="owner456",
    )
    print(result["is_encrypted"])

Convert pages to images

from toolkitapi import PDF

with PDF(api_key="tk_...") as pdf:
    result = pdf.to_images(
        url="https://toolkitapi.io/report.pdf",
        pages="1-2",
        format="jpeg",
        dpi=200,
    )
    print(result["rendered_pages"])

Parameter reference

Split, rotate, compress, watermark, to-images (query params)

Parameter Endpoint(s) Type Default Description
url all string — Required. Public URL of the PDF (max 2048 chars)
pages split string all all for individual pages, or ranges like 1-3,5,8-10
pages others string null Pages to process. Omit for all pages
angle rotate integer — Required. 90, 180, or 270 clockwise
angle watermark integer 45 0–360 degrees
text watermark string — Required. 1–200 chars
font_size watermark integer 48 8–200 px
opacity watermark float 0.15 0.01–1.0
format to-images string png png or jpeg
dpi to-images integer 150 72–600. Higher = larger and sharper

Merge / protect (JSON body)

Parameter Endpoint Type Description
pdf_urls merge array Required. 2–20 PDF URLs, merged in order
url protect string Required. Public URL of the PDF
action protect string encrypt or decrypt
user_password protect string 1–128 chars. Required for encrypt (at least one of user/owner)
owner_password protect string 1–128 chars
allow_printing protect boolean Permission flag when encrypting
allow_copying protect boolean Permission flag when encrypting

Error cases

Status When it happens Fix
400 URL #N does not point to a valid PDF (merge) Confirm every pdf_urls entry resolves to a real PDF
400 PDF #N is malformed: ... (merge) The file is corrupt or password-protected; decrypt it first
400 Action must be 'encrypt' or 'decrypt' action is case-sensitive
400 At least one of user_password or owner_password is required for encryption Supply at least one password
400 Could not parse the PDF File is not a readable PDF
401 Missing or invalid X-API-Key Send the header
405 You POSTed JSON to split/rotate/compress/watermark/to-images Those are GET — use query params
422 angle missing on rotate, or not one of 90/180/270 Pass a valid rotation
422 dpi outside 72–600, or opacity outside 0.01–1.0 Clamp to the documented range
422 pdf_urls has fewer than 2 or more than 20 entries Merge accepts 2–20 files

Tips

  • Most routes are GET. Use curl -G --data-urlencode, requests.get(params=...), or URLSearchParams for split, rotate, compress, watermark, and to-images. Only merge and protect take JSON bodies.
  • All PDF outputs are base64 in a pdf field — merge, split parts, rotate, compress, watermark, and protect. Decode with base64.b64decode before writing to disk.
  • split always returns a parts array, even when you pass a single range. With the default pages=all you get one entry per page, which is handy for page-by-page pipelines.
  • compress takes no quality knob. If the savings aren't enough, to-images at a modest dpi and re-stitching gives you finer control.
  • Use to-images before OCR only when you need visual page output for a downstream workflow. The dedicated GET /v1/pdf/ocr route renders pages internally and returns text directly — no round-trip through image files needed.
  • protect handles both directions in one route: encrypt adds passwords, decrypt removes them. For decrypt, pass the existing password so the file can be opened.
  • Order matters for merge. Pages are concatenated in the order of pdf_urls; sort your inputs before calling.