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: true means /v1/pdf/text and friends will fail to read the content until you run /v1/pdf/protect with action: "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/metadata surfaces keywords on write but not in the read response — read keywords back 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, so pages.length always equals extracted_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/text on page 1; if word_count is 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. pypdf returns reading-order-ish plain text; multi-column layouts may interleave. For tables, use /v1/pdf/table-extract.
  • Normalise before analysis. page["text"].split() is what word_count uses, 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.