Inspect & Extract Text — Info, Metadata & Page Text¶
Three endpoints for reading a PDF before you process it:
| Endpoint | Method | Purpose |
|---|---|---|
/v1/pdf/info |
GET |
Structure: page count, per-page dimensions, rotation, version, encryption, basic authoring metadata |
/v1/pdf/metadata |
POST |
Read the full metadata dictionary, and optionally rewrite it |
/v1/pdf/text |
GET |
Extract text page by page, with word/char counts |
Base URL: https://pdf.toolkitapi.io
Input model: all three take a public URL of the PDF (http/https, ≤ 2048 chars). The API downloads the file; authenticated URLs are not supported.
Text extraction uses the PDF's embedded text layer (pypdf). Scanned/image-only PDFs return empty strings — run them through /v1/pdf/ocr instead.
Structural info — GET /v1/pdf/info¶
Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
url |
string | ✅ | Public URL of the PDF |
Request¶
curl "https://pdf.toolkitapi.io/v1/pdf/info?url=https://example.com/annual-report.pdf" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://pdf.toolkitapi.io/v1/pdf/info",
headers={"X-API-Key": "YOUR_KEY"},
params={"url": "https://example.com/annual-report.pdf"},
timeout=60,
)
resp.raise_for_status()
info = resp.json()
print(f"{info['page_count']} pages, {info['file_size']:,} bytes, PDF {info['pdf_version']}")
print("encrypted:", info["is_encrypted"])
for page in info["pages"][:3]:
print(page["page"], f"{page['width_inches']}x{page['height_inches']}in", f"rot={page['rotation']}")
const params = new URLSearchParams({ url: "https://example.com/annual-report.pdf" });
const resp = await fetch(`https://pdf.toolkitapi.io/v1/pdf/info?${params}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) throw new Error(`Info failed: ${resp.status} ${await resp.text()}`);
const info = await resp.json();
console.log(`${info.page_count} pages, PDF ${info.pdf_version}, encrypted=${info.is_encrypted}`);
const sizes = new Set(info.pages.map((p) => `${p.width}x${p.height}`));
console.log("distinct page sizes:", sizes.size);
Response¶
{
"page_count": 24,
"file_size": 3128477,
"pdf_version": "%PDF-1.7",
"is_encrypted": false,
"title": "Annual Report 2026",
"author": "Acme Corp",
"creator": "InDesign 19.2",
"producer": "Adobe PDF Library 17.0",
"pages": [
{
"page": 1,
"width": 595.28,
"height": 841.89,
"width_inches": 8.27,
"height_inches": 11.69,
"rotation": 0
}
]
}
| Field | Type | Description |
|---|---|---|
page_count |
int | Total pages |
file_size |
int | Source size in bytes |
pdf_version |
string | null | PDF header, e.g. %PDF-1.7 |
is_encrypted |
bool | Whether the file is encrypted |
title / author / creator / producer |
string | null | Info-dictionary basics (null when absent) |
pages[].page |
int | 1-based page number |
pages[].width / height |
float | Media box size in PDF points (72 pt = 1 in), 2 dp |
pages[].width_inches / height_inches |
float | Same in inches, 2 dp |
pages[].rotation |
int | Existing /Rotate value (0, 90, 180, 270) |
Tip:
is_encrypted: truemeans/v1/pdf/textand friends will fail to read the content until you run/v1/pdf/protectwithaction: "decrypt".
Metadata — POST /v1/pdf/metadata¶
Reads the document info dictionary. If you pass update, it also returns a rewritten PDF with the new values.
Parameters (JSON body)¶
| Field | Type | Required | Description |
|---|---|---|---|
url |
string | ✅ | Public URL of the PDF |
update |
object | null | ❌ | Metadata fields to set. Omit to read only |
Valid update keys: title, author, subject, creator, producer, keywords. Any other key → 400 Invalid metadata keys: ….
Values must be strings. Passing null/empty string clears nothing in practice — it writes an empty value, which most readers render as blank.
Request — read¶
curl -X POST "https://pdf.toolkitapi.io/v1/pdf/metadata" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/report.pdf"}'
Request — update¶
curl -X POST "https://pdf.toolkitapi.io/v1/pdf/metadata" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/report.pdf",
"update": {
"title": "Q3 Financial Summary",
"author": "Finance Team",
"keywords": "finance, quarterly, 2026"
}
}'
import base64
import requests
resp = requests.post(
"https://pdf.toolkitapi.io/v1/pdf/metadata",
headers={"X-API-Key": "YOUR_KEY"},
json={
"url": "https://example.com/report.pdf",
"update": {
"title": "Q3 Financial Summary",
"author": "Finance Team",
"keywords": "finance, quarterly, 2026",
},
},
timeout=120,
)
resp.raise_for_status()
data = resp.json()
print(data["metadata"])
if data["pdf"]: # only present when update was applied
with open("report-retagged.pdf", "wb") as f:
f.write(base64.b64decode(data["pdf"]))
const resp = await fetch("https://pdf.toolkitapi.io/v1/pdf/metadata", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
url: "https://example.com/report.pdf",
update: { title: "Q3 Financial Summary", author: "Finance Team", keywords: "finance, quarterly, 2026" },
}),
});
if (!resp.ok) throw new Error(`Metadata failed: ${resp.status} ${await resp.text()}`);
const data = await resp.json();
console.log(data.metadata.title, "-", data.page_count, "pages");
if (data.pdf) console.log("updated PDF:", Buffer.from(data.pdf, "base64").length, "bytes");
Response (read)¶
{
"metadata": {
"title": "Annual Report 2026",
"author": "Acme Corp",
"subject": "Financials",
"creator": "InDesign 19.2",
"producer": "Adobe PDF Library 17.0",
"creation_date": "2026-02-11 09:14:22+00:00",
"modification_date": "2026-02-11 09:14:22+00:00"
},
"page_count": 24,
"pdf_version": "%PDF-1.7",
"pdf": null,
"file_size": 3128477
}
Response (update)¶
Same shape, but pdf holds the base64 of the rewritten file and metadata reflects the merged values.
| Field | Type | Description |
|---|---|---|
metadata |
object | Metadata fields (existing + applied updates) |
page_count |
int | Page count |
pdf_version |
string | null | PDF header |
pdf |
string | null | Rewritten PDF as base64 — only when update was provided |
file_size |
int | Source size (read) or updated file size (update) |
Note:
/v1/pdf/metadatasurfaceskeywordson write but not in the read response — readkeywordsback via/v1/pdf/info's authoring fields or a local parser if you need to verify.
Text extraction — GET /v1/pdf/text¶
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url |
string | ✅ | — | Public URL of the PDF |
pages |
string | ❌ | all pages | Page spec: 5, 1-3, 1-3,5,8-10 (1-based, inclusive) |
Request¶
curl "https://pdf.toolkitapi.io/v1/pdf/text?url=https://example.com/contract.pdf&pages=1-3" \
-H "X-API-Key: YOUR_KEY"
import requests
resp = requests.get(
"https://pdf.toolkitapi.io/v1/pdf/text",
headers={"X-API-Key": "YOUR_KEY"},
params={"url": "https://example.com/contract.pdf", "pages": "1-3"},
timeout=120,
)
resp.raise_for_status()
data = resp.json()
for page in data["pages"]:
print(f"--- page {page['page']} ({page['word_count']} words) ---")
print(page["text"][:400])
full_text = "\n\n".join(p["text"] for p in data["pages"])
print(f"\n{data['total_word_count']} words across {data['extracted_pages']}/{data['total_pages']} pages")
const params = new URLSearchParams({
url: "https://example.com/contract.pdf",
pages: "1-3",
});
const resp = await fetch(`https://pdf.toolkitapi.io/v1/pdf/text?${params}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) throw new Error(`Text extraction failed: ${resp.status} ${await resp.text()}`);
const data = await resp.json();
const fullText = data.pages.map((p) => p.text).join("\n\n");
console.log(`${data.total_word_count} words, pages: ${data.pages.map((p) => p.page).join(", ")}`);
Response¶
{
"pages": [
{ "page": 1, "text": "MASTER SERVICES AGREEMENT\n\nThis Agreement is made…", "word_count": 412, "char_count": 2764 },
{ "page": 2, "text": "1. Definitions\n\n\"Affiliate\" means…", "word_count": 388, "char_count": 2510 }
],
"total_pages": 12,
"extracted_pages": 2,
"total_word_count": 800,
"total_char_count": 5274
}
| Field | Type | Description |
|---|---|---|
pages[].page |
int | 1-based page number |
pages[].text |
string | Extracted text (empty string if no text layer) |
pages[].word_count |
int | Whitespace-delimited words |
pages[].char_count |
int | Characters including whitespace |
total_pages |
int | Pages in the source document |
extracted_pages |
int | Pages returned in pages |
total_word_count / total_char_count |
int | Sums across extracted pages |
Tip: blank pages are included with
text: ""and zero counts, sopages.lengthalways equalsextracted_pages. Use this to detect pages that need OCR:
python needs_ocr = [p["page"] for p in data["pages"] if p["word_count"] == 0]
Error cases¶
| Endpoint | Status | Condition | detail |
|---|---|---|---|
| all | 400 |
Downloaded content isn't a parseable PDF | Could not parse the PDF |
| all | 422 |
Missing url or url > 2048 chars |
FastAPI validation error |
| metadata | 400 |
Unknown key in update |
Invalid metadata keys: foo. Valid: author, creator, keywords, producer, subject, title |
| text | 400 |
Malformed page spec | Invalid page range: '…' |
| text | 400 |
Page beyond document length | Page range '9-14' out of bounds (PDF has 12 pages) |
| all | 413 |
Source exceeds download size limit | payload too large |
Encrypted PDFs: /v1/pdf/info succeeds (returns is_encrypted: true), but /v1/pdf/text and /v1/pdf/metadata return 400 Could not parse the PDF because the content can't be decrypted without a password. Decrypt first via /v1/pdf/protect.
Tips¶
- Check before you pay for OCR. Run
/v1/pdf/info(cheap) then/v1/pdf/texton page 1; ifword_countis 0, go to/v1/pdf/ocr. - Extract selectively. Page specs keep responses small — a 300-page manual can easily exceed several MB of JSON.
- Layout is flattened.
pypdfreturns reading-order-ish plain text; multi-column layouts may interleave. For tables, use/v1/pdf/table-extract. - Normalise before analysis.
page["text"].split()is whatword_countuses, so reuse the same splitting for consistency. - Combine with metadata updates. Retagging scraped PDFs (
update: {title, author}) plus extracting text is a common ingestion pattern and both accept URLs, so you need one re-host step between them.
Related endpoints¶
/v1/pdf/ocrand/v1/pdf/table-extract— for scanned documents and tabular data/v1/pdf/protect— decrypt before extraction/v1/pdf/compress— shrink huge documents before pulling text