PQ PDF Developer API

◎ Overview

The PQ PDF API is a REST gateway that proxies authenticated requests to the same processing engine that powers pqpdf.com. Every tool available in the web UI is available via the API.

⬡ Authentication

Every request (except GET /v1/health and GET /v1/operations) requires an API key passed in the X-API-Key request header. Keys are shown only once at creation time — store them securely.

◈ Rate Limits

Limits are tracked per API key, per calendar hour (UTC). Polling and pagination operations are exempt to avoid counter inflation.

Exempt from rate counting: edit-ping, edit-page, pdf-scan-poll, esign-status, esign-preview

⚠ Error Codes

All error responses include a JSON body: {"success": false, "error": "message"}

◉ Request Format

All operation requests are POST to /v1/{operation} using multipart/form-data. Upload the PDF as the file field and any operation parameters as additional text fields.

curl --http3-only -X POST https://api.pqpdf.com/v1/compress \
  -H "X-API-Key: pqpdf_your_key_here" \
  -F "file=@document.pdf" \
  -F "quality=ebook" \
  -o compressed.pdf

from curl_cffi.requests import Session

with Session(http_version=3) as client:
    resp = client.post(
        "https://api.pqpdf.com/v1/compress",
        headers={"X-API-Key": "pqpdf_your_key_here"},
        files={"file": open("document.pdf", "rb")},
        data={"quality": "ebook"},
    )
with open("compressed.pdf", "wb") as f:
    f.write(resp.content)

// Node 18+ — undici fetch (HTTP/3 via QUIC, Alt-Svc negotiation)
import { fetch, Agent } from "undici";
import fs from "fs";

const dispatcher = new Agent({ allowH2: true });

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("document.pdf")]));
form.append("quality", "ebook");

const resp = await fetch("https://api.pqpdf.com/v1/compress", {
    method: "POST",
    headers: { "X-API-Key": "pqpdf_your_key_here" },
    body: form,
    dispatcher,
});
fs.writeFileSync("compressed.pdf", Buffer.from(await resp.arrayBuffer()));

$ch = curl_init("https://api.pqpdf.com/v1/compress");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_3,
    CURLOPT_HTTPHEADER     => ["X-API-Key: pqpdf_your_key_here"],
    CURLOPT_POSTFIELDS     => [
        "file"    => new CURLFile("document.pdf"),
        "quality" => "ebook",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
file_put_contents("compressed.pdf", curl_exec($ch));
curl_close($ch);

⬡ Key Management

Create and manage API keys and their IP whitelists. All routes require a valid X-API-Key and operate on that key's owner account.

{
  "success": true,
  "keys": [
    {
      "id":                  "uuid",
      "label":               "primary",
      "key_prefix":          "pqpdf_02ef5e22",
      "is_active":           true,
      "created_at":          "2026-04-09T17:31:45Z",
      "last_used_at":        "2026-04-09T19:00:00Z",
      "rate_limit_per_hour": 100,
      "rate_limit_per_day":  500,
      "ip_count":            2
    }
  ]
}

{
  "success": true,
  "message": "Save this key — it will not be shown again.",
  "key": {
    "id":                  "uuid",
    "label":               "production",
    "key_prefix":          "pqpdf_a1b2c3d4",
    "api_key":             "pqpdf_a1b2c3d4...",
    "rate_limit_per_hour": 200,
    "rate_limit_per_day":  1000
  }
}

{ "success": true, "revoked": "uuid" }

◎ IP Whitelist

Attach IP addresses or CIDR ranges to a key. When any entries exist, requests from IPs not matching any entry are rejected with 403.

{
  "success": true,
  "ips": [
    { "id": "uuid", "cidr": "203.0.113.0/24", "label": "office", "created_at": "..." }
  ]
}

{ "success": true, "ip": { "id": "uuid", "cidr": "203.0.113.5", "label": "my-server" } }

{ "success": true, "removed": "uuid" }

◈ Usage Stats

{
  "success": true,
  "current_key_id":       "uuid",
  "usage_this_hour":      12,
  "rate_limit_per_hour":  100,
  "last_30_days": [
    { "operation": "compress", "total": 48, "avg_ms": 210.5, "total_bytes": 9437184 },
    { "operation": "get-info", "total": 24, "avg_ms":  85.2, "total_bytes":   12288 }
  ]
}

◉ List Operations

{
  "success": true,
  "operations": ["merge", "split", "compress", ...],
  "stateful_operations": ["edit-init", "edit-page", "esign-create", ...],
  "note": "For stateful operations, include X-Session-Id header with a UUID."
}

⬡ Core PDF Tools

All operations: POST /v1/{operation} with X-API-Key header and multipart/form-data body. Fields marked file are binary uploads; all others are text fields.

Available workflow operations: rotate, compress, watermark, protect, unlock, grayscale, flatten, repair, extract-pages, delete-pages, reorder, pdfa, sign, redact, split-every. Each step object uses the same parameter names as the standalone operation.

⇄ Conversion

Convert between PDF and Office formats, images, HTML, and Markdown.

Response header X-Pdf-Compare-Stats contains compared, different, and identical page counts. Output is a PDF with page-by-page diff images (red = removed, green = added, grey = unchanged).

◉ OCR

✎ PDF Editor Stateful

The editor operates on a live in-memory PDF session. Start with edit-init, make changes with subsequent calls sharing the same X-Session-Id, then call edit-apply to render and download the final PDF.

⬡ PDF Forensics Scanner

Deep forensic analysis — 44 detection engines, YARA rules, sandbox emulation, ML scoring, and AI-generated forensic summary. Large files are scanned asynchronously.

{ "started": true, "token": "pdftool_abc123..." }

{ "ready": false, "progress": "Extracting embedded objects..." }

{
  "ready": true,
  "risk_score": 82,
  "risk_level": "high-risk",
  "ai_forensic_summary": {
    "threat_verdict": "SUSPICIOUS",
    "confidence": "MEDIUM",
    "executive_summary": "PDF contains obfuscated JavaScript with network callbacks.",
    "key_findings": [
      { "signal": "JavaScript eval() with base64 payload", "severity": "HIGH", "mitre_id": "T1059.007" }
    ],
    "recommended_actions": ["Do not open this file", "Submit to sandbox for dynamic analysis"]
  }
}

The synchronous pdf-scan operation accepts files up to 10 MB; larger files must use the async pdf-scan-start / pdf-scan-poll flow (up to 50 MB). On-premise removes the cap entirely →

⬡ Office Forensics

Deep forensic scanning and surgical sanitization for Office documents (.docx, .xlsx, .pptx, .doc, .xls, .ppt, .xlsm, .docm, .pptm, .rtf, .msg, .eml and more). Eight dedicated engines cover macros, XLM, OLE objects, metadata, IOCs, and container structure — with an AI-generated forensic summary. Sanitize endpoints return a cleaned file; the scanner uses an async job queue.

Submit an Office document for forensic analysis. Returns immediately; poll for results.

{ "job_id": "b42f57f8-449e-4a3f-97dc-baec65ac03a2", "status": "queued" }

Poll scan status. Rate-exempt — polling does not consume your hourly quota. Returns scanning while in progress; full JSON report on completion.

{ "status": "scanning" }

{
  "status": "complete",
  "result": {
    "file_info": { "filename": "report.docx", "size_bytes": 38000, "format": "DOCX" },
    "risk_assessment": {
      "level": "CRITICAL",
      "total_score": 95,
      "findings_count": 8
    },
    "all_findings": [
      { "engine": "macros", "severity": "critical", "finding": "VBA AutoOpen macro detected", "mitre": "T1137" },
      { "engine": "ioc",    "severity": "high",     "finding": "Suspicious URL: http://evil.example/payload" }
    ],
    "ai_forensic_summary": {
      "threat_verdict": "MALICIOUS",
      "confidence": "HIGH",
      "executive_summary": "Document contains an AutoOpen macro that downloads a remote payload.",
      "recommended_actions": ["Do not open", "Submit to sandbox"]
    }
  }
}

Render via LibreOffice to a flat PDF. Destroys all macros, VBA, XLM, OLE objects, and active content with certainty. The safest sanitization option. Returns application/pdf.

Surgically remove all VBA and XLM macros while preserving document content, formatting, and structure. Returns the sanitized document in the same format as the input.

Remove all document metadata: author, revision history, last-saved-by, company name, and custom properties. Returns the sanitized document in the same format as the input.

Upgrade legacy .doc / .xls / .ppt (OLE2 binary format) to modern .docx / .xlsx / .pptx (OOXML). Eliminates the OLE2 exploit surface while preserving document content.

# Submit
curl --http3-only https://api.pqpdf.com/v1/office-scan \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@report.docx"
# → {"job_id":"b42f57f8...","status":"queued"}

# Poll (no rate-limit cost)
curl --http3-only https://api.pqpdf.com/v1/office-scan/b42f57f8-449e-4a3f-97dc-baec65ac03a2 \
  -H "X-API-Key: YOUR_KEY"

curl --http3-only https://api.pqpdf.com/v1/office-sanitize/pdf \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@report.docx" \
  -o report_safe.pdf

🔬 File Fingerprint Comparator

Submit two PDF or Office documents for independent scanning, then diff their structural fingerprints across 25+ security features — VBA macros, IOC extraction, OLE structure, YARA matches, ClamAV verdict, encryption, JavaScript, XFA, URL/IP counts, threat intelligence, risk scores, and more. Returns a similarity percentage, variant verdict (IDENTICAL / NEAR_IDENTICAL / SIMILAR / PARTIALLY_SIMILAR / DIFFERENT), and a differences-first field-level comparison table. Use it for malware variant detection, suspicious attachment triage, and document integrity verification.

Submit one PDF or Office document for forensic fingerprint scanning. Call this twice — once per file — to get two job IDs for the diff step.

{ "job_id": "b42f57f8-449e-4a3f-97dc-baec65ac03a2", "status": "queued" }

Poll the scan status of a submitted file. Rate-exempt — polling does not consume your hourly quota. Call until status = complete before requesting the diff.

{ "status": "scanning" }

{ "status": "complete" }

{ "status": "error", "error": "Scan failed: unsupported file type" }

Compute the structural fingerprint diff between two completed scans. Both job IDs must be in complete status. Rate-exempt.

{
  "similarity_pct": 87.4,
  "verdict": "SIMILAR",
  "file_a": { "filename": "invoice_v1.docx", "format": "DOCX", "risk_score": 12 },
  "file_b": { "filename": "invoice_v2.docx", "format": "DOCX", "risk_score": 45 },
  "diff": [
    {
      "group": "Macro",
      "feature": "has_macros",
      "file_a": false,
      "file_b": true,
      "match": false
    },
    {
      "group": "IOC",
      "feature": "url_count",
      "file_a": 0,
      "file_b": 3,
      "match": false
    }
  ],
  "matching": [
    { "group": "Container", "feature": "container_type", "value": "OOXML", "match": true }
  ]
}

# Step 1 — submit File A
curl --http3-only -X POST https://api.pqpdf.com/v1/file-compare/scan \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@invoice_v1.docx"
# → {"job_id":"b42f57f8-449e-4a3f-97dc-baec65ac03a2","status":"queued"}

# Step 2 — submit File B
curl --http3-only -X POST https://api.pqpdf.com/v1/file-compare/scan \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@invoice_v2.docx"
# → {"job_id":"c91a3d12-8f4e-4b5a-ae01-d7bc22fe1098","status":"queued"}

# Step 3 — poll until both are complete
curl --http3-only "https://api.pqpdf.com/v1/file-compare/scan/b42f57f8-449e-4a3f-97dc-baec65ac03a2" \
  -H "X-API-Key: YOUR_KEY"
# → {"status":"complete"}

# Step 4 — compute diff
curl --http3-only "https://api.pqpdf.com/v1/file-compare/diff?job_a=b42f57f8-449e-4a3f-97dc-baec65ac03a2&job_b=c91a3d12-8f4e-4b5a-ae01-d7bc22fe1098" \
  -H "X-API-Key: YOUR_KEY"

◈ Form Fill Stateful

Fill PDF form fields programmatically. Initialize the session, then apply field values.

{
  "success": true,
  "token": "pdftool_abc123",
  "fields": [
    { "name": "first_name", "type": "text", "value": "" },
    { "name": "agree",      "type": "checkbox", "value": "Off" }
  ]
}

◉ Outline / Bookmarks Stateful

✍ eSign Workflow Stateful

Create multi-party signature workflows. Up to 10 signers (sequential or parallel). The requester can lock signing field controls, assign multiple Sign Here / Initial Here boxes per signer per page, and enforce PAdES-B cryptographic signatures. Each signer gets a unique secure link — no account needed. Track progress with esign-status; download the completed PDF with esign-download.

▦ Layout

◎ Inspection

◈ Standards

◉ AI-Powered Tools

Self-hosted AI analysis — no OpenAI, no external calls. Runs on the local Qwen 2.5 model.

◎ Camera Scan

⇄ Guide: Stateful Sessions

Editor, form fill, outline, eSign, and async scan operations maintain server-side PHP session state. You must pass a consistent X-Session-Id header across all calls in the same workflow.

SESSION="$(uuidgen)"
KEY="pqpdf_your_key_here"

# 1. Open PDF in editor
curl --http3-only -X POST https://api.pqpdf.com/v1/edit-init \
  -H "X-API-Key: $KEY" -H "X-Session-Id: $SESSION" \
  -F "file=@document.pdf"
# → { "token": "pdftool_abc123", "page_count": 5, ... }

# 2. Add text to page 1
curl --http3-only -X POST https://api.pqpdf.com/v1/edit-doc-op \
  -H "X-API-Key: $KEY" -H "X-Session-Id: $SESSION" \
  -F "token=pdftool_abc123" \
  -F 'op_type=add_text' \
  -F 'page=1' \
  -F 'data={"x":100,"y":200,"text":"APPROVED","font_size":24,"color":"#ff0000"}'

# 3. Download edited PDF
curl --http3-only -X POST https://api.pqpdf.com/v1/edit-apply \
  -H "X-API-Key: $KEY" -H "X-Session-Id: $SESSION" \
  -F "token=pdftool_abc123" \
  -o edited.pdf

import uuid
from curl_cffi.requests import Session

SESSION = str(uuid.uuid4())
KEY     = "pqpdf_your_key_here"
HEADERS = {"X-API-Key": KEY, "X-Session-Id": SESSION}
BASE    = "https://api.pqpdf.com/v1"

with Session(http_version=3) as client:
    # 1. Open PDF
    init  = client.post(f"{BASE}/edit-init", headers=HEADERS,
                        files={"file": open("document.pdf", "rb")}).json()
    token = init["token"]

    # 2. Queue text annotation
    client.post(f"{BASE}/edit-doc-op", headers=HEADERS, data={
        "token":   token,
        "op_type": "add_text",
        "page":    1,
        "data":    '{"x":100,"y":200,"text":"APPROVED","font_size":24,"color":"#ff0000"}',
    })

    # 3. Download result
    resp = client.post(f"{BASE}/edit-apply", headers=HEADERS,
                       data={"token": token})
with open("edited.pdf", "wb") as f:
    f.write(resp.content)

⌂ Code Examples

KEY="pqpdf_your_key_here"
SESSION="$(uuidgen)"

# Start async scan
TOKEN=$(curl -s --http3-only -X POST https://api.pqpdf.com/v1/pdf-scan-start \
  -H "X-API-Key: $KEY" -H "X-Session-Id: $SESSION" \
  -F "file=@suspect.pdf" | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Poll until ready
while true; do
  RESULT=$(curl -s --http3-only -X POST https://api.pqpdf.com/v1/pdf-scan-poll \
    -H "X-API-Key: $KEY" -H "X-Session-Id: $SESSION" \
    -F "token=$TOKEN")
  READY=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('ready','false'))")
  [ "$READY" = "True" ] && echo "$RESULT" && break
  sleep 3
done

import uuid, time
from curl_cffi.requests import Session

KEY     = "pqpdf_your_key_here"
SESSION = str(uuid.uuid4())
HEADERS = {"X-API-Key": KEY, "X-Session-Id": SESSION}
BASE    = "https://api.pqpdf.com/v1"

with Session(http_version=3) as client:
    # Start
    resp  = client.post(f"{BASE}/pdf-scan-start", headers=HEADERS,
                        files={"file": open("suspect.pdf", "rb")}).json()
    token = resp["token"]

    # Poll
    while True:
        result = client.post(f"{BASE}/pdf-scan-poll", headers=HEADERS,
                             data={"token": token}).json()
        if result.get("ready"):
            print(result["risk_level"], result["ai_forensic_summary"]["threat_verdict"])
            break
        time.sleep(3)

KEY="pqpdf_your_key_here"

# Create a new key
curl -s --http3-only -X POST https://api.pqpdf.com/v1/keys \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci-pipeline","rate_limit_per_hour":500}'

# Add an IP to the new key
NEW_KEY_ID="<uuid from above>"
curl -s --http3-only -X POST https://api.pqpdf.com/v1/keys/$NEW_KEY_ID/ips \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"cidr":"10.0.0.0/8","label":"internal-network"}'

from curl_cffi.requests import Session

KEY     = "pqpdf_your_key_here"
HEADERS = {"X-API-Key": KEY}
BASE    = "https://api.pqpdf.com/v1"

with Session(http_version=3) as client:
    # Create key
    new    = client.post(f"{BASE}/keys", headers=HEADERS, json={
        "label": "ci-pipeline", "rate_limit_per_hour": 500
    }).json()
    key_id = new["key"]["id"]
    print("New key:", new["key"]["api_key"])  # save this!

    # Whitelist IP
    client.post(f"{BASE}/keys/{key_id}/ips", headers=HEADERS, json={
        "cidr": "10.0.0.0/8", "label": "internal-network"
    })