Documentation

Getting Started

LintPDF is a detection-only PDF preflight engine. You send a file, you get a report. Three steps to your first Report:

Quick example

# Submit a PDF for preflight
curl -X POST https://api.lintpdf.com/api/v1/submit \
  -H "Authorization: Bearer lpdf_your_api_key" \
  -F file=@brochure.pdf \
  -F ruleset=gwg-sheetfed

# Retrieve the Report
curl https://api.lintpdf.com/api/v1/reports/f47ac10b-... \
  -H "Authorization: Bearer lpdf_your_api_key"

Authentication

Include your API Key in the Authorization header as a Bearer token:

Authorization: Bearer lpdf_your_api_key

API Reference

Base URL: https://api.lintpdf.com

All endpoints return JSON. Authenticated endpoints require a valid API Key.

curl -X POST https://api.lintpdf.com/api/v1/submit \
  -H "Authorization: Bearer lpdf_..." \
  -F file=@document.pdf \
  -F ruleset=gwg-sheetfed

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "ruleset": "gwg-sheetfed",
  "file_name": "document.pdf",
  "created_at": "2026-03-15T10:30:00Z"
}

curl https://api.lintpdf.com/api/v1/reports/f47ac10b-... \
  -H "Authorization: Bearer lpdf_..."

{
  "id": "f47ac10b-...",
  "status": "complete",
  "verdict": "error",
  "ruleset": "gwg-sheetfed",
  "file_name": "document.pdf",
  "page_count": 4,
  "duration_ms": 1240,
  "summary": {
    "total_findings": 3,
    "error": 1,
    "warning": 1,
    "info": 1
  },
  "findings": [
    {
      "inspection_id": "font.not_embedded",
      "severity": "error",
      "message": "Font 'Helvetica' is not embedded",
      "page": 1
    },
    {
      "inspection_id": "color.spot_color_usage",
      "severity": "warning",
      "message": "Spot color 'PANTONE 185 C' found on page 2",
      "page": 2
    },
    {
      "inspection_id": "image.low_resolution",
      "severity": "info",
      "message": "Image at 150 DPI (minimum 300 DPI recommended)",
      "page": 3
    }
  ]
}

# PDF report (white-labeled)
curl -o report.pdf \
  "https://api.lintpdf.com/api/v1/reports/f47ac10b-.../report?format=pdf" \
  -H "Authorization: Bearer lpdf_..."

# JSON report
curl "https://api.lintpdf.com/api/v1/reports/f47ac10b-.../report?format=json" \
  -H "Authorization: Bearer lpdf_..."

200 OK
Content-Type: application/pdf (or application/json, application/xml)

# JSON format returns the same structure as GET /api/v1/reports/{id}
# PDF format returns a branded, downloadable report
# XML format returns a structured XML document

curl -X PUT https://api.lintpdf.com/api/v1/white-label \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://yourcompany.com/logo.png",
    "primary_color": "#1a365d",
    "company_name": "Acme Print Co.",
    "footer_text": "Preflight report generated by Acme Print Co."
  }'

{
  "white_label": {
    "logo_url": "https://yourcompany.com/logo.png",
    "primary_color": "#1a365d",
    "company_name": "Acme Print Co.",
    "footer_text": "Preflight report generated by Acme Print Co.",
    "updated_at": "2026-03-15T10:30:00Z"
  }
}

curl https://api.lintpdf.com/api/v1/rulesets

{
  "rulesets": [
    {
      "id": "gwg-sheetfed",
      "name": "GWG Sheetfed",
      "description": "Ghent Workgroup sheetfed offset standard",
      "checks": 196,
      "is_builtin": true
    },
    {
      "id": "gwg-digital",
      "name": "GWG Digital",
      "description": "Ghent Workgroup digital printing standard",
      "checks": 180,
      "is_builtin": true
    },
    {
      "id": "pdfx4",
      "name": "PDF/X-4",
      "description": "ISO 15930-7 PDF/X-4 conformance",
      "checks": 120,
      "is_builtin": true
    },
    {
      "id": "packaging",
      "name": "Packaging",
      "description": "Packaging-specific checks including barcode grading",
      "checks": 210,
      "is_builtin": true
    }
  ]
}

curl -X POST https://api.lintpdf.com/api/v1/rulesets \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Plan",
    "description": "Custom checks for magazine production",
    "base": "gwg-sheetfed",
    "overrides": {
      "image.min_dpi": 300,
      "barcode.min_grade": "C",
      "color.allow_spot": true
    }
  }'

{
  "id": "fp_custom_abc123",
  "name": "My Custom Plan",
  "description": "Custom checks for magazine production",
  "checks": 196,
  "is_builtin": false,
  "created_at": "2026-03-15T10:30:00Z"
}

Rulesets

A Ruleset is a preflight profile — a collection of Checks and thresholds that define what LintPDF checks for. Every submission requires a Ruleset.

Built-in Rulesets

Custom Rulesets

Growth, Scale, and Enterprise plans can create custom Rulesets. Start from a built-in base and override specific thresholds, enable or disable individual Checks, and name your profile for reuse across submissions.

Checks Reference

LintPDF runs 250+ individual Checks across these categories. Each finding in a Report references a Check ID, severity level, and affected page.

This is a representative sample. The full suite includes 250+ checks. Use the GET /api/v1/rulesets endpoint to see which Checks are included in each Ruleset.

Report Formats

Reports can be retrieved in three formats. Use the format query parameter on the report endpoint.

JSON Response Schema

{
  "id": "string",
  "status": "complete",
  "verdict": "pass | error",
  "ruleset": "string",
  "file_name": "string",
  "page_count": "number",
  "duration_ms": "number",
  "summary": {
    "total_findings": "number",
    "error": "number",
    "warning": "number",
    "info": "number"
  },
  "findings": [
    {
      "inspection_id": "string",
      "severity": "error | warning | info",
      "message": "string",
      "page": "number"
    }
  ]
}

PDF Reports & White Label

PDF reports are white-labeled using your White Label configuration. Scale and Enterprise plans can upload a logo, set brand colors, and customize footer text. Reports include a summary page, detailed findings grouped by severity, and page-level annotations.

XML Format

XML reports follow the same structure as JSON but use XML elements. Useful for legacy integrations and enterprise systems that consume XML.

<?xml version="1.0" encoding="UTF-8"?>
<report id="f47ac10b-..." status="complete" verdict="error">
  <ruleset>gwg-sheetfed</ruleset>
  <file-name>document.pdf</file-name>
  <summary total="3" error="1" warning="1" info="1" />
  <findings>
    <finding inspection="font.not_embedded" severity="error" page="1">
      Font 'Helvetica' is not embedded
    </finding>
  </findings>
</report>

Webhooks

Webhooks are webhook callbacks. Register an endpoint and LintPDF will POST event payloads when files finish processing. No polling required.

Registering a Webhook

curl -X POST https://api.lintpdf.com/api/v1/webhooks \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["job.complete", "job.error"]
  }'

Event Types

Webhook Payload

{
  "event": "job.complete",
  "timestamp": "2026-03-15T10:30:01Z",
  "data": {
    "id": "f47ac10b-...",
    "verdict": "error",
    "ruleset": "gwg-sheetfed",
    "file_name": "document.pdf",
    "summary": {
      "total_findings": 3,
      "error": 1,
      "warning": 1,
      "info": 1
    }
  }
}

SDKs & Code Examples

LintPDF is a standard REST API — use any HTTP client. Here are examples in popular languages.

Python

import httpx

client = httpx.Client(
    base_url="https://api.lintpdf.com",
    headers={"Authorization": "Bearer lpdf_your_api_key"},
)

# Submit a PDF
with open("brochure.pdf", "rb") as f:
    resp = client.post("/api/v1/submit", files={"file": f}, data={"ruleset": "gwg-sheetfed"})
    job = resp.json()

print(f"Job ID: {job['id']}, Status: {job['status']}")

# Retrieve the Report
report = client.get(f"/api/v1/reports/{job['id']}").json()

if report["verdict"] == "pass":
    print("Pass!")
else:
    print(f"Error: {report['summary']['error']} Error findings")
    for finding in report["findings"]:
        print(f"  [{finding['severity']}] {finding['message']} (page {finding['page']})")

Node.js

import fs from "node:fs";

const API_BASE = "https://api.lintpdf.com";
const headers = { Authorization: "Bearer lpdf_your_api_key" };

// Submit a PDF
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("brochure.pdf")]));
form.append("ruleset", "gwg-sheetfed");

const job = await fetch(`${API_BASE}/api/v1/submit`, {
  method: "POST",
  headers,
  body: form,
}).then((r) => r.json());

console.log("Job ID:", job.id, "Status:", job.status);

// Retrieve the Report
const report = await fetch(`${API_BASE}/api/v1/reports/${job.id}`, {
  headers,
}).then((r) => r.json());

console.log("Verdict:", report.verdict);

PHP / Laravel

use Illuminate\Support\Facades\Http;

$apiBase = 'https://api.lintpdf.com';
$headers = ['Authorization' => 'Bearer lpdf_your_api_key'];

// Submit a PDF
$response = Http::withHeaders($headers)
    ->attach('file', file_get_contents('brochure.pdf'), 'brochure.pdf')
    ->post("$apiBase/api/v1/submit", [
        'ruleset' => 'gwg-sheetfed',
    ]);

$job = $response->json();

// Retrieve the Report
$report = Http::withHeaders($headers)
    ->get("$apiBase/api/v1/reports/{$job['id']}")
    ->json();

if ($report['verdict'] === 'pass') {
    echo "Pass!";
} else {
    echo "Error: " . $report['summary']['error'] . " Error findings";
}

Glossary

LintPDF terminology reference.

AI Getting Started

AI features are available as an invite-only alpha on all paid plans. Four steps to your first AI-powered Report:

Quick example

# Submit a PDF with FDA AI preset
curl -X POST https://api.lintpdf.com/api/v1/submit \
  -H "Authorization: Bearer lpdf_your_api_key" \
  -F file=@food-label.pdf \
  -F ruleset=packaging \
  -F ai_preset=fda-food

# Report includes both core engine and AI findings
curl https://api.lintpdf.com/api/v1/reports/f47ac10b-... \
  -H "Authorization: Bearer lpdf_your_api_key"

# Check your credit balance
curl https://api.lintpdf.com/api/v1/ai/credits \
  -H "Authorization: Bearer lpdf_your_api_key"

AI Configuration

AI features are configured at three levels: account defaults, Ruleset settings, and per-request overrides.

Account-Level Settings

In Settings > AI Inspections, enable or disable entire AI categories. These serve as defaults for all submissions.

Brand Configuration

For brand-related AI inspections, configure your assets in Settings > AI Brand:

• Color Palette — Add approved brand colors as hex values with Delta E tolerance
• Reference Logos — Upload logo variations (horizontal, stacked, icon-only, reversed)
• Custom Dictionary — Add brand names, product names, and technical terms for spell checking

Confidence Threshold

Set the minimum confidence score for AI findings in Settings > AI Inspections. Default is 0.75. Only findings above this threshold appear in your Report.

AI Credits

Core preflight checks are unlimited on paid plans. AI inspections consume credits — 1 credit for Text-tier, 2 credits for Vision-tier.

Pricing

Checking Balance

curl https://api.lintpdf.com/api/v1/ai/credits \
  -H "Authorization: Bearer lpdf_..."

# Response
{
  "balance": 4250,
  "billing_mode": "package",
  "auto_topup": false,
  "consumed_this_month": 750,
  "consumed_total": 3250
}

Auto Top-up

curl -X PUT https://api.lintpdf.com/api/v1/ai/credits/auto-topup \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 100,
    "package": "starter"
  }'

AI Inspections Reference

Complete reference for all 33 AI inspections, organized by category.

AI Presets

Pre-built collections of AI inspections for common use cases. Use a preset ID in your Submit request to run a curated set of AI inspections.

Listing Presets via API

curl https://api.lintpdf.com/api/v1/ai/presets \
  -H "Authorization: Bearer lpdf_..."

# Response
{
  "presets": [
    {
      "id": "fda-food",
      "name": "FDA Food",
      "inspections": 12,
      "categories": ["barcode", "content_quality", "regulatory_fda"],
      "tier": "gpu"
    },
    ...
  ]
}

Regulatory Compliance Guide

LintPDF validates packaging artwork against four regulatory frameworks. See the full compliance page for detailed check lists and example findings.

AI API Reference

All AI endpoints require a valid API Key and AI features enabled on your account.

curl -X POST https://api.lintpdf.com/api/v1/submit \
  -H "Authorization: Bearer lpdf_..." \
  -F file=@label.pdf \
  -F ruleset=packaging \
  -F ai_preset=fda-food

# Or specify categories directly:
curl -X POST https://api.lintpdf.com/api/v1/submit \
  -H "Authorization: Bearer lpdf_..." \
  -F file=@label.pdf \
  -F ruleset=packaging \
  -F ai_categories=barcode,regulatory_fda,content_quality

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "ruleset": "packaging",
  "ai_preset": "fda-food",
  "ai_inspections_requested": 12,
  "file_name": "label.pdf",
  "created_at": "2026-03-16T10:30:00Z"
}

curl https://api.lintpdf.com/api/v1/ai/credits \
  -H "Authorization: Bearer lpdf_..."

{
  "balance": 4250,
  "billing_mode": "package",
  "auto_topup": false,
  "consumed_this_month": 750,
  "consumed_total": 3250
}

curl -X POST https://api.lintpdf.com/api/v1/ai/credits/topup \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{"package": "starter"}'

{
  "balance": 5250,
  "package_purchased": "starter",
  "credits_added": 1000,
  "amount_charged": "$50.00"
}

curl -X PUT https://api.lintpdf.com/api/v1/ai/credits/auto-topup \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "threshold": 100,
    "package": "starter"
  }'

{
  "auto_topup": {
    "enabled": true,
    "threshold": 100,
    "package": "starter"
  }
}

curl https://api.lintpdf.com/api/v1/ai/presets \
  -H "Authorization: Bearer lpdf_..."

{
  "presets": [
    {
      "id": "fda-food",
      "name": "FDA Food",
      "inspections": 12,
      "categories": ["barcode", "content_quality", "regulatory_fda"],
      "tier": "gpu"
    },
    {
      "id": "full-ai",
      "name": "Full AI Scan",
      "inspections": 33,
      "categories": ["all"],
      "tier": "gpu"
    }
  ]
}

curl -X PUT https://api.lintpdf.com/api/v1/ai/brand/palette \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "colors": [
      {"hex": "#1a365d", "name": "Primary Navy"},
      {"hex": "#3b6fb5", "name": "Secondary Blue"},
      {"hex": "#e2a832", "name": "Accent Gold"}
    ],
    "tolerance": 5
  }'

{
  "palette": {
    "colors": [
      {"hex": "#1a365d", "name": "Primary Navy"},
      {"hex": "#3b6fb5", "name": "Secondary Blue"},
      {"hex": "#e2a832", "name": "Accent Gold"}
    ],
    "tolerance": 5,
    "updated_at": "2026-03-16T10:30:00Z"
  }
}

curl -X POST https://api.lintpdf.com/api/v1/ai/brand/logos \
  -H "Authorization: Bearer lpdf_..." \
  -F file=@logo-horizontal.png \
  -F name="Horizontal Logo" \
  -F variant="horizontal"

{
  "logo": {
    "id": "logo_abc123",
    "name": "Horizontal Logo",
    "variant": "horizontal",
    "file_type": "image/png",
    "created_at": "2026-03-16T10:30:00Z"
  }
}

curl -X PUT https://api.lintpdf.com/api/v1/ai/brand/dictionary \
  -H "Authorization: Bearer lpdf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "words": ["LintPDF", "PreflightPro", "XtraShield"],
    "mode": "append"
  }'

{
  "dictionary": {
    "word_count": 47,
    "mode": "append",
    "words_added": 3,
    "updated_at": "2026-03-16T10:30:00Z"
  }
}

AI Error Reference

AI-specific error codes that may appear in API responses or Report info notes.

AI Code Examples

Examples showing how to enable AI inspections in job submissions across different languages.

Python — FDA Food Label Check

import httpx

client = httpx.Client(
    base_url="https://api.lintpdf.com",
    headers={"Authorization": "Bearer lpdf_your_api_key"},
)

# Submit with FDA AI preset
with open("nutrition-label.pdf", "rb") as f:
    resp = client.post(
        "/api/v1/submit",
        files={"file": f},
        data={
            "ruleset": "packaging",
            "ai_preset": "fda-food",
        },
    )
    job = resp.json()

print(f"Job ID: {job['id']}")

# Retrieve Report
report = client.get(f"/api/v1/reports/{job['id']}").json()

# Separate core and AI findings
engine_findings = [f for f in report["findings"] if f.get("source") != "ai"]
ai_findings = [f for f in report["findings"] if f.get("source") == "ai"]

print(f"Core engine: {len(engine_findings)} findings")
print(f"AI: {len(ai_findings)} findings")

for finding in ai_findings:
    print(f"  [{finding['severity']}] {finding['message']}")
    print(f"    Confidence: {finding.get('confidence', 'N/A')}")
    print(f"    Credits: {finding.get('credits_consumed', 'N/A')}")

Node.js — GHS Chemical Label Check

import fs from "node:fs";

const API_BASE = "https://api.lintpdf.com";
const headers = { Authorization: "Bearer lpdf_your_api_key" };

// Check credit balance first
const credits = await fetch(`${API_BASE}/api/v1/ai/credits`, { headers })
  .then((r) => r.json());

console.log("Credit balance:", credits.balance);

if (credits.balance < 20) {
  console.warn("Low credit balance — consider topping up");
}

// Submit with GHS preset
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("chemical-label.pdf")]));
form.append("ruleset", "packaging");
form.append("ai_preset", "ghs-chemical");

const job = await fetch(`${API_BASE}/api/v1/submit`, {
  method: "POST",
  headers,
  body: form,
}).then((r) => r.json());

console.log("Job:", job.id, "AI inspections:", job.ai_inspections_requested);

// Retrieve Report
const report = await fetch(`${API_BASE}/api/v1/reports/${job.id}`, {
  headers,
}).then((r) => r.json());

// Filter by regulatory findings
const ghsFindings = report.findings.filter(
  (f) => f.category === "regulatory.ghs"
);

console.log("GHS findings:", ghsFindings.length);
ghsFindings.forEach((f) => console.log(`  [${f.severity}] ${f.message}`));

PHP / Laravel — Brand Compliance Check

use Illuminate\Support\Facades\Http;

$apiBase = 'https://api.lintpdf.com';
$headers = ['Authorization' => 'Bearer lpdf_your_api_key'];

// Submit with brand compliance preset
$response = Http::withHeaders($headers)
    ->attach('file', file_get_contents('packaging-artwork.pdf'), 'packaging-artwork.pdf')
    ->post("$apiBase/api/v1/submit", [
        'ruleset' => 'packaging',
        'ai_preset' => 'brand-compliance',
    ]);

$job = $response->json();

// Retrieve Report
$report = Http::withHeaders($headers)
    ->get("$apiBase/api/v1/reports/{$job['id']}")
    ->json();

// Filter AI findings by brand category
$brandFindings = collect($report['findings'])
    ->filter(fn($f) => str_starts_with($f['category'] ?? '', 'brand'))
    ->values();

foreach ($brandFindings as $finding) {
    echo "[{$finding['severity']}] {$finding['message']}\n";
    echo "  Confidence: {$finding['confidence']}\n";
}