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. Usecurl -G --data-urlencode,requests.get(params=...), orURLSearchParamsforsplit,rotate,compress,watermark, andto-images. Onlymergeandprotecttake JSON bodies. - All PDF outputs are base64 in a
pdffield —merge,splitparts,rotate,compress,watermark, andprotect. Decode withbase64.b64decodebefore writing to disk. splitalways returns apartsarray, even when you pass a single range. With the defaultpages=allyou get one entry per page, which is handy for page-by-page pipelines.compresstakes no quality knob. If the savings aren't enough,to-imagesat a modestdpiand re-stitching gives you finer control.- Use
to-imagesbefore OCR only when you need visual page output for a downstream workflow. The dedicatedGET /v1/pdf/ocrroute renders pages internally and returns text directly — no round-trip through image files needed. protecthandles both directions in one route:encryptadds passwords,decryptremoves them. Fordecrypt, pass the existing password so the file can be opened.- Order matters for
merge. Pages are concatenated in the order ofpdf_urls; sort your inputs before calling.