Authentication & rate limits

All authenticated endpoints require a Bearer token issued from the Dashboard. Keys are prefixed lpdf_live_ for production and lpdf_test_ for sandbox.

Authorization: Bearer lpdf_live_...

Rate-limit headers

Every job-submit response (POST /api/v1/jobs and the vanity /endpoints/{slug}/submit) carries the following headers. Use them to back off gracefully before a 429 is returned.

X-RateLimit-Limit: 5000           # Files included in the current billing cycle
X-RateLimit-Used: 412             # Files consumed so far this cycle
X-RateLimit-Remaining: 4588       # Files remaining before overage kicks in

# The next four only appear once you've exceeded the included allowance:
X-RateLimit-Overage: true              # Boolean flag — present = in overage
X-RateLimit-Overage-Count: 12          # Files billed at the overage rate this cycle
X-RateLimit-Overage-Rate-Cents: 10     # Per-file overage cost in cents
X-RateLimit-Overage-Cost-Cents: 120    # Accrued overage cost this cycle

The overage headers are omitted entirely while you are inside your plan's included allowance — treat their absence as “no overage”.

Error envelope

Errors use FastAPI's default JSON shape. Status codes follow HTTP semantics; the detail field carries the human-readable message.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "detail": "preflight_source must be one of: engine, external, minimal"
}

Request-validation errors (malformed body, missing required fields) follow FastAPI's structured form with detail as an array of { loc, msg, type } entries.

Jobs

A Job is one file submitted for processing. Jobs carry a status, findings, reports, and (optionally) a preflight source. LintPDF supports three submission modes via preflight_source: engine (run our analyzers), external (import findings from your own preflight tool), and minimal (viewer-only, no analysis).

curl -X POST https://api.lintpdf.com/api/v1/jobs \
  -H "Authorization: Bearer lpdf_live_..." \
  -F file=@brochure.pdf \
  -F profile_id=lintpdf-default \
  -F preflight_source=engine

{
  "job_id": "d4e5f6a7-1234-4567-89ab-cdef01234567",
  "status": "pending",
  "message": "Job submitted successfully"
}

Request fields

Status codes

curl https://api.lintpdf.com/api/v1/jobs/d4e5f6a7-... \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "status": "complete",
  "profile_id": "lintpdf-default",
  "file_name": "brochure.pdf",
  "file_size": 842139,
  "page_count": 12,
  "created_at": "2026-04-12T10:30:00Z",
  "completed_at": "2026-04-12T10:30:04Z",
  "duration_ms": 3480,
  "summary": {
    "total_findings": 7,
    "error_count": 1,
    "warning_count": 4,
    "advisory_count": 2,
    "passed": false,
    "page_count": 12,
    "file_size_bytes": 842139
  },
  "findings": [
    {
      "inspection_id": "font.not_embedded",
      "severity": "error",
      "message": "Font 'Helvetica' is not embedded",
      "page_num": 1,
      "bbox": [72.0, 720.0, 540.0, 740.0],
      "object_id": "Font12",
      "object_type": "font",
      "category": "fonts",
      "source": "engine",
      "audit": {
        "status": "confirmed",
        "rationale": "Helvetica glyph references with no matching /FontFile entry.",
        "model": "modal:qwen2-vl-7b",
        "at": "2026-04-22T18:05:34Z"
      }
    }
  ],
  "reports": {
    "pdf": "https://reports.lintpdf.com/r/abc123.pdf",
    "html": "https://reports.lintpdf.com/r/abc123"
  }
}

Capability flags (separations, tac, fonts, images, layers) live on the viewer config (GET /viewer/jobs/{id}/config), not on the job payload.

curl "https://api.lintpdf.com/api/v1/jobs?page=1&page_size=25" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "jobs": [ { "job_id": "...", "status": "complete", "file_name": "...", "created_at": "..." } ],
  "total": 418,
  "page": 1,
  "page_size": 25
}

curl -X DELETE https://api.lintpdf.com/api/v1/jobs/d4e5f6a7-... \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 204 No Content

Universal job state

GET /api/v1/jobs/{job_id}/state returns preflight results, every minted report URL, the approval chain (with each approver's notes), the manual verdict, and every viewer annotation with its comment thread embedded — in one call. Previously this required 3+ round trips and an N+1 fan-out for comments. See the dedicated Universal Job State page for the full field table and a runnable example payload.

curl "https://api.lintpdf.com/api/v1/jobs/d4e5f6a7-.../state" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job": { "job_id": "...", "status": "complete", "summary": { "passed": true, "total_findings": 2 } },
  "reports": [
    { "format": "annotated_pdf", "url": "https://reports.lintpdf.com/r/...", "token": "...",
      "allow_annotations": false, "require_visitor_email": null }
  ],
  "approval_chain": {
    "status": "approved", "current_step": 0,
    "step_history": [
      { "step_name": "Print ops", "approver_email": "ops@example.com",
        "decision": "approved", "notes": "Looks great, ship it." }
    ]
  },
  "verdict": { "verdict": "approved", "auto_passed": true, "notes": "..." },
  "annotations": {
    "total": 1, "by_page": { "1": 1 },
    "items": [
      { "id": "...", "page_num": 1, "kind": "rect", "text": "Fix the bleed",
        "comments": [ { "body": "Will do by EOD.", "author_email": "..." } ] }
    ]
  }
}

Share-link mirror: GET /api/v1/viewer/public/{token}/state returns the same shape minus the reports section (listing sibling share-link tokens from a single token would leak shares that weren't handed to the current visitor).

Custom submission endpoints

Growth-tier customers can mint vanity slugs and give customers a branded submission URL instead of /api/v1/jobs. Each endpoint has a response_mode setting: async (default) returns 202 + job_id so the caller polls GET /api/v1/jobs/{id}; sync blocks the submit request until the job is terminal and returns the full JobResponse inline. A per-request ?wait= query param can override either way (useful for integrations like Zapier / n8n / Make.com that can't orchestrate a polling loop).

# Async (default)
curl -X POST https://api.lintpdf.com/api/v1/endpoints/acme-proofs/submit \
  -H "Authorization: Bearer lpdf_live_..." \
  -F file=@brochure.pdf

# Sync (wait inline for the verdict)
curl -X POST "https://api.lintpdf.com/api/v1/endpoints/acme-proofs/submit?wait=60" \
  -H "Authorization: Bearer lpdf_live_..." \
  -F file=@brochure.pdf

# 202 Accepted (async)
{ "job_id": "d4e5f6a7-...", "status": "pending", "message": "Job submitted successfully" }

# 200 OK (sync, reached terminal within wait budget)
{ "job_id": "d4e5f6a7-...", "status": "complete", "summary": { ... }, "findings": [ ... ], "reports": { ... } }

Endpoint fields

External imports & custom mappings

When preflight_source=external, submit the report alongside the PDF. LintPDF parses PitStop XML, callas JSON/XML, Acrobat Preflight XML, and our native v1 JSON schema directly. For any other shape, define a tenant-scoped custom mapping.

curl -X POST https://api.lintpdf.com/api/v1/tenant/import-mappings \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal QA XML",
    "description": "Maps our in-house preflight XML to LintPDF findings.",
    "format": "xml",
    "config": {
      "item_selector": "Findings/Finding",
      "fields": {
        "severity": { "selector": "@level" },
        "message":  { "selector": "Description" },
        "page_num": { "selector": "Page", "parse": "int" },
        "bbox":     { "selector": "BBox", "format": "space_xywh" },
        "inspection_id": { "selector": "@rule" }
      },
      "severity_map": { "S": "error", "W": "warning", "N": "advisory" },
      "default_severity": "warning"
    },
    "sample_payload": "<Findings>...</Findings>",
    "sample_mime": "application/xml",
    "is_active": true
  }'

{
  "id": "2f7c1e8a-1b4d-4e1a-9a2b-9c8d7e6f5a4b",
  "name": "Internal QA XML",
  "description": "Maps our in-house preflight XML to LintPDF findings.",
  "format": "xml",
  "config": { "item_selector": "Findings/Finding", "fields": { ... } },
  "sample_payload": "<Findings>...</Findings>",
  "sample_mime": "application/xml",
  "is_active": true,
  "created_at": "2026-04-12T10:30:00Z",
  "updated_at": "2026-04-12T10:30:00Z"
}

Mapping request fields

curl "https://api.lintpdf.com/api/v1/tenant/import-mappings" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "mappings": [
    {
      "id": "2f7c1e8a-...",
      "name": "Internal QA XML",
      "description": "Maps our in-house preflight XML to LintPDF findings.",
      "format": "xml",
      "config": { ... },
      "sample_payload": "<Findings>...</Findings>",
      "sample_mime": "application/xml",
      "is_active": true,
      "created_at": "2026-04-12T10:30:00Z",
      "updated_at": "2026-04-12T10:30:00Z"
    }
  ]
}

curl https://api.lintpdf.com/api/v1/tenant/import-mappings/2f7c1e8a-... \
  -H "Authorization: Bearer lpdf_live_..."

{ "id": "2f7c1e8a-...", "name": "Internal QA XML", "format": "xml", "config": {...}, "is_active": true, ... }

curl -X PUT https://api.lintpdf.com/api/v1/tenant/import-mappings/2f7c1e8a-... \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal QA XML",
    "format": "xml",
    "config": { ... },
    "is_active": false
  }'

{ "id": "2f7c1e8a-...", "is_active": false, ... }

curl -X DELETE https://api.lintpdf.com/api/v1/tenant/import-mappings/2f7c1e8a-... \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 204 No Content

curl -X POST https://api.lintpdf.com/api/v1/tenant/import-mappings/2f7c1e8a-.../preview \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "config": { "item_selector": "Findings/Finding", "fields": { ... } },
    "sample_payload": "<Findings>...</Findings>"
  }'

{
  "ok": true,
  "findings_count": 12,
  "sample_findings": [
    {
      "severity": "error",
      "message": "Image resolution too low",
      "page_num": 3,
      "inspection_id": "IMG_LOWRES",
      "bbox": [72, 720, 540, 740],
      "object_id": "Im4",
      "object_type": "image",
      "category": "Images"
    }
  ],
  "error": null
}

Both request fields are optional: when omitted, preview uses the mapping's stored config and sample_payload. Supply them to iterate on a config in the editor before saving. Returns at most the first 5 findings in sample_findings.

Branding & custom domains

LintPDF resolves branding in three modes: anonymous (no brand at all), lintpdf (our default branding), or a specific tenant BrandProfile by UUID. The submit form brand field overrides the tenant default on a per-request basis.

curl https://api.lintpdf.com/api/v1/tenant/branding-defaults \
  -H "Authorization: Bearer lpdf_live_..."

{
  "mode": "profile",
  "unbranded_by_default": false,
  "default_brand_profile_id": "2f7c1e8a-1b4d-4e1a-9a2b-9c8d7e6f5a4b"
}

curl -X PATCH https://api.lintpdf.com/api/v1/tenant/branding-defaults \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "mode": "anonymous" }'

{
  "mode": "anonymous",
  "unbranded_by_default": true,
  "default_brand_profile_id": null
}

The response also carries unbranded_by_default (mirrors the tenant flag) and default_brand_profile_id (the currently-pinned profile, or null).

Brand profiles

curl https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles \
  -H "Authorization: Bearer lpdf_live_..."

{ "profiles": [ { "id": "...", "name": "Acme Print", "profile_type": "custom", ... } ] }

curl -X POST https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Print",
    "profile_type": "custom",
    "brand_name": "Acme Print",
    "logo_url": "https://acmeprint.com/logo.svg",
    "primary_color": "#1a365d",
    "accent_color": "#2563eb",
    "footer_text": "Preflight by Acme Print",
    "hide_footer": false
  }'

{
  "id": "9f8e7d6c-5b4a-4321-9876-543210fedcba",
  "name": "Acme Print",
  "profile_type": "custom",
  "brand_name": "Acme Print",
  "logo_url": "https://acmeprint.com/logo.svg",
  "primary_color": "#1a365d",
  "accent_color": "#2563eb",
  "footer_text": "Preflight by Acme Print",
  "hide_footer": false,
  "is_default": false,
  "created_at": "2026-04-12T10:30:00Z",
  "updated_at": "2026-04-12T10:30:00Z"
}

BrandProfile fields

curl https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles/PROFILE \
  -H "Authorization: Bearer lpdf_live_..."

{ "id": "...", "name": "Acme Print", ... }

curl -X PUT https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles/PROFILE \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "primary_color": "#0f172a", "hide_footer": true }'

{ "id": "...", "primary_color": "#0f172a", "hide_footer": true, ... }

curl -X DELETE https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles/PROFILE \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 204 No Content

curl -X POST https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles/PROFILE/logo \
  -H "Authorization: Bearer lpdf_live_..." \
  -F file=@logo.png

{ "id": "...", "logo_url": "https://cdn.lintpdf.com/brand-logos/...", ... }

curl -X PATCH https://api.lintpdf.com/api/v1/tenants/TENANT/default-brand-profile \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "brand_profile_id": "9f8e7d6c-..." }'

{ "id": "9f8e7d6c-...", "is_default": true, ... }

Custom report domain

White-label reports on reports.yourbrand.com. One CNAME record per hostname pointing at edge.lintpdf.com— LintPDF's Caddy edge on Fly.io issues a Let's Encrypt certificate on first request and path-routes to the right backend. No ACME TXT records, no manual cert installation. Scale/Enterprise only — the engine returns 403 on lower tiers.

curl https://api.lintpdf.com/api/v1/tenants/TENANT/custom-domain \
  -H "Authorization: Bearer lpdf_live_..."

{
  "tenant_id": "...",
  "domain": "reports.acmeprint.com",
  "verified": false,
  "requested_at": "2026-04-12T10:30:00Z",
  "plan_allows_whitelabel": true,
  "dns_target": "edge.lintpdf.com"
}

curl -X PATCH https://api.lintpdf.com/api/v1/tenants/TENANT/custom-domain \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "reports.acmeprint.com" }'

{
  "tenant_id": "...",
  "domain": "reports.acmeprint.com",
  "verified": false,
  "requested_at": "2026-04-12T10:30:00Z",
  "plan_allows_whitelabel": true,
  "dns_target": "edge.lintpdf.com"
}

To clear the domain, PATCH with { "domain": null }.

Per-BrandProfile domain

Agencies serving multiple end-clients can point each BrandProfile at its own subdomain.

curl -X PATCH \
  https://api.lintpdf.com/api/v1/tenants/TENANT/brand-profiles/PROFILE/custom-domain \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "proofs.end-brand.com" }'

{ "id": "...", "custom_domain": "proofs.end-brand.com", "custom_domain_verified": false, ... }

App / viewer domain

curl https://api.lintpdf.com/api/v1/tenants/TENANT/app-custom-domain \
  -H "Authorization: Bearer lpdf_live_..."

{
  "tenant_id": "...",
  "domain": "app.acmeprint.com",
  "verified": false,
  "requested_at": "2026-04-12T10:30:00Z",
  "plan_allows_whitelabel": true
}

curl -X PATCH https://api.lintpdf.com/api/v1/tenants/TENANT/app-custom-domain \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "app.acmeprint.com" }'

{
  "tenant_id": "...",
  "domain": "app.acmeprint.com",
  "verified": false,
  "requested_at": "2026-04-12T10:30:00Z",
  "plan_allows_whitelabel": true
}

BrandSpecs — per-customer color specifications

A BrandSpec is a named color specification a tenant maintains per end-customer — swatches, optional rich-black, and flags. The resolver walks job.brand_spec_id → endpoint.default_brand_spec_id → tenant-default spec and applies the first hit. When nothing resolves, strict color advisories stay suppressed.

curl https://api.lintpdf.com/api/v1/brand-specs \
  -H "Authorization: Bearer lpdf_live_..."

{
  "brand_specs": [
    {
      "id": "...",
      "name": "Coca-Cola",
      "customer_name": "Coca-Cola Co.",
      "colors": [{"name": "Coke Red", "value": "#F40009", "pantone": "PMS 185 C"}],
      "rich_black_spec": {"c": 60, "m": 50, "y": 50, "k": 100},
      "is_default": true,
      "is_archived": false
    }
  ]
}

curl -X POST https://api.lintpdf.com/api/v1/brand-specs \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coca-Cola",
    "customer_name": "Coca-Cola Co.",
    "colors": [{"name": "Coke Red", "value": "#F40009"}],
    "is_default": true
  }'

{
  "id": "brand-spec-uuid",
  "name": "Coca-Cola",
  "customer_name": "Coca-Cola Co.",
  "colors": [{"name": "Coke Red", "value": "#F40009"}],
  "rich_black_spec": null,
  "is_default": true,
  "is_archived": false
}

BrandSpec fields

curl -X PATCH https://api.lintpdf.com/api/v1/brand-specs/SPEC_ID \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "colors": [{"name": "New", "value": "#123456"}] }'

{
  "id": "brand-spec-uuid",
  "name": "Coca-Cola",
  "customer_name": "Coca-Cola Co.",
  "colors": [{"name": "New", "value": "#123456"}],
  "rich_black_spec": null,
  "is_default": true,
  "is_archived": false
}

curl -X DELETE https://api.lintpdf.com/api/v1/brand-specs/SPEC_ID \
  -H "Authorization: Bearer lpdf_live_..."

{
  "id": "brand-spec-uuid",
  "is_archived": true,
  "is_default": false
}

curl -X POST https://api.lintpdf.com/api/v1/brand-specs/SPEC_ID/restore \
  -H "Authorization: Bearer lpdf_live_..."

{
  "id": "brand-spec-uuid",
  "is_archived": false,
  "is_default": false
}

Viewer

The Viewer surface lets you embed or build a PDF viewer against any complete job — engine, external, or minimal. Tiles, separations, TAC heatmaps, densitometer samples, and layer metadata are served as JSON/PNG from a dedicated route group.

curl https://api.lintpdf.com/api/v1/viewer/jobs/d4e5f6a7-.../pages \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "page_count": 1,
  "pages": [
    {
      "page_num": 1,
      "width_pts": 595.28,
      "height_pts": 841.89,
      "media_box": { "x0": 0, "y0": 0, "x1": 595.28, "y1": 841.89 },
      "crop_box":  { "x0": 0, "y0": 0, "x1": 595.28, "y1": 841.89 },
      "trim_box":  { "x0": 14.17, "y0": 14.17, "x1": 581.10, "y1": 827.72 },
      "bleed_box": null,
      "rotation": 0
    }
  ]
}

curl "https://api.lintpdf.com/api/v1/viewer/jobs/d4e5f6a7-.../pages/1/tile?dpi=200&ocg_on=0,3&ocg_off=2" \
  -H "Authorization: Bearer lpdf_live_..." \
  --output page-1.png

200 OK
Content-Type: image/png
# 422 if ocg_on/ocg_off conflict, indices are out of range, or the PDF has no OCGs.

Separations & channels

curl https://api.lintpdf.com/api/v1/viewer/jobs/d4e5f6a7-.../separations \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "channels": [
    { "name": "Cyan", "type": "process" },
    { "name": "Magenta", "type": "process" },
    { "name": "Yellow", "type": "process" },
    { "name": "Black", "type": "process" },
    { "name": "PANTONE 185 C", "type": "spot" }
  ]
}

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../pages/1/channel/PANTONE+185+C?dpi=150" \
  -H "Authorization: Bearer lpdf_live_..." \
  --output pantone-185c-page1.png

200 OK
Content-Type: image/png

TAC heatmap & densitometer

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../pages/1/tac-heatmap?tac_limit=300" \
  -H "Authorization: Bearer lpdf_live_..." \
  --output tac-page1.png

200 OK
Content-Type: image/png

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../pages/1/tac-heatmap/runs?tac_limit=300" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "page_num": 1,
  "dpi": 150,
  "tac_limit": 300.0,
  "runs": [
    { "x0": 102.3, "y0": 88.1, "x1": 440.7, "y1": 112.5, "mean_tac": 342.8, "limit": 300.0, "exceeds": true }
  ]
}

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../pages/1/sample?x=200&y=300" \
  -H "Authorization: Bearer lpdf_live_..."

{ "x": 200, "y": 300, "rgb": [12, 99, 180], "hex": "#0c63b4", "tac": null }

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../pages/1/densitometer?x=200&y=300" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "x": 200, "y": 300, "dpi": 300,
  "channels": [
    { "name": "Cyan", "percent": 62.3 },
    { "name": "Magenta", "percent": 18.1 },
    { "name": "Yellow", "percent": 4.7 },
    { "name": "Black", "percent": 91.5 }
  ],
  "tac": 176.6,
  "tac_limit": 300,
  "limit_exceeded": false
}

Tile pre-warming progress

curl https://api.lintpdf.com/api/v1/viewer/jobs/.../tile-warming \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "status": "in_progress",
  "rendered": 7,
  "total": 20,
  "dpi": 150,
  "percent": 35,
  "started_at": "2026-04-14T10:22:13Z",
  "completed_at": null,
  "error": null
}

Layers

curl https://api.lintpdf.com/api/v1/viewer/jobs/.../layers \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "layers": [
    { "name": "Varnish", "ocg_index": 0, "default_on": true },
    { "name": "Dieline", "ocg_index": 1, "default_on": false }
  ]
}

Viewer config

curl "https://api.lintpdf.com/api/v1/viewer/jobs/.../config?brand=lintpdf" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "enable_separations": true,
  "enable_tac_heatmap": true,
  "enable_annotations": true,
  "enable_measurement": true,
  "enable_comparison": true,
  "enable_layers": true,
  "enable_findings_panel": true,
  "enable_page_thumbnails": true,
  "enable_zoom": true,
  "enable_download": true,
  "enable_html_report_link": true,
  "verdict_mode": "auto",
  "default_zoom": 100,
  "default_dpi": 150,
  "default_tac_limit": 300.0,
  "viewer_logo_url": null,
  "viewer_accent_color": null,
  "toolbar_position": "top",
  "dark_mode": false,
  "brand_name": "LintPDF",
  "brand_logo_url": "https://lintpdf.com/logo.svg",
  "brand_primary_color": "#1a3a7a",
  "brand_accent_color": "#2563eb",
  "anonymous": false,
  "tenant_name": "Acme Print",
  "support_email": "support@acmeprint.com",
  "preflight_source": "engine",
  "capabilities": {
    "separations": true, "tac": true, "tac_runs": true, "tiles_warmed": true,
    "fonts": true, "images": true, "layers": false,
    "text_regions": false,
    "ai_explain": true, "epm_verdict": true
  },
  "capability_fillin_enabled": true,
  "annotations_enabled": true,
  "allowed_report_formats": ["json", "html", "pdf", "xml"]
}

Viewer config fields

On-demand capability fill-in

Missing analyzer output can be filled lazily. Fillable capabilities: separations, tac, fonts, images. layers is read-only (detected at parse time).

curl -X POST https://api.lintpdf.com/api/v1/viewer/jobs/.../capabilities/separations \
  -H "Authorization: Bearer lpdf_live_..."

{
  "job_id": "d4e5f6a7-...",
  "capability": "separations",
  "status": "queued",
  "task_id": "tsk_01HXY..."
}

When the capability is already populated the response comes back with status: "already_filled" and no task_id. Non-fillable capabilities return 422.

# Python polling pattern
import time, requests
r = requests.post(f"{BASE}/viewer/jobs/{jid}/capabilities/tac", headers=H)
while True:
    cfg = requests.get(f"{BASE}/viewer/jobs/{jid}/config", headers=H).json()
    if cfg["capabilities"].get("tac"):
        break
    time.sleep(1.5)

Verdict

curl https://api.lintpdf.com/api/v1/viewer/jobs/.../verdict \
  -H "Authorization: Bearer lpdf_live_..."

{
  "verdict": "pass",
  "auto_passed": true,
  "verdict_by": "reviewer@acmeprint.com",
  "verdict_at": "2026-04-12T15:22:11Z",
  "notes": null
}

curl -X POST https://api.lintpdf.com/api/v1/viewer/jobs/.../verdict \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "verdict": "fail", "notes": "Low-res image on page 4" }'

{
  "verdict": "fail",
  "auto_passed": false,
  "verdict_by": "reviewer@acmeprint.com",
  "verdict_at": "2026-04-12T15:22:11Z",
  "notes": "Low-res image on page 4"
}

auto_passed reflects the engine's summary verdict; verdict reflects a reviewer's manual call. A job can be auto-passed and manually failed at the same time — clients should render both.

File comparison

curl -X POST https://api.lintpdf.com/api/v1/viewer/compare \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "job_a": "d4e5f6a7-...", "job_b": "a1b2c3d4-...", "dpi": 150 }'

{
  "comparison_id": "cmp_8e7d6c5b4a3f",
  "page_count_a": 12,
  "page_count_b": 12,
  "pages": [
    { "page_num": 1, "ssim_score": 0.987, "diff_pixel_count": 1842, "total_pixels": 1404000 }
  ]
}

curl "https://api.lintpdf.com/api/v1/viewer/compare/cmp_.../pages/1/diff?dpi=150" \
  -H "Authorization: Bearer lpdf_live_..." \
  --output diff-page1.png

200 OK
Content-Type: image/png

Annotations + comments

GET /api/v1/viewer/jobs/{job_id}/annotations returns the flat annotation list by default (back-compat). Pass ?include=comments to embed each annotation's full comment thread inline in one round trip — no N+1 fan-out of per-annotation comment fetches. The aggregated GET /api/v1/jobs/{id}/state endpoint uses the same embedding.

curl "https://api.lintpdf.com/api/v1/viewer/jobs/d4e5f6a7-.../annotations?include=comments" \
  -H "Authorization: Bearer lpdf_live_..."

[
  {
    "id": "...", "page_num": 1, "kind": "rect",
    "geometry": { "x": 10, "y": 10, "w": 100, "h": 50 },
    "color": "#dc2626", "text": "Fix the bleed",
    "author_email": "reviewer@example.com",
    "comments": [
      { "id": "...", "annotation_id": "...",
        "author_email": "reviewer@example.com", "body": "Will do by EOD." }
    ]
  }
]

The same ?include=comments param works on the share-link mirror GET /api/v1/viewer/public/{token}/annotations?include=comments — unauthenticated read, subject to the token's expiry.

Public share-link state digest

Mirror of the authenticated universal-state endpoint for share links. Returns the same stitched digest (summary + approval chain + verdict + annotations + comments) minus the reports section — those are scoped to the issuing tenant and shouldn't leak sibling tokens. See Universal Job State for the full field reference.

curl "https://api.lintpdf.com/api/v1/viewer/public/CahsfLjcly.../state?include=verdict,annotations"

{
  "job": { "job_id": "...", "status": "complete" },
  "summary": { "total_findings": 275, "passed": true },
  "approval_chain": { "status": "approved", "step_history": [ ... ] },
  "verdict": { "verdict": "pass", "auto_passed": true, "notes": "..." },
  "annotations": { "total": 1, "by_page": {"1": 1}, "items": [ ... ] }
}

Reports & share links

Reports are immutable artifacts minted from a complete job. Each report carries its own token for unauthenticated access and freezes its branding at mint time — flipping the tenant default later does not retroactively rebrand existing share links.

curl -X POST https://api.lintpdf.com/api/v1/jobs/d4e5f6a7-.../reports \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-42-2026-04-17" \
  -d '{
    "formats": [
      { "format": "json", "return": "inline" },
      { "format": "annotated_pdf", "return": "url" },
      "html"
    ],
    "expiry_days": 14,
    "email_to": "printer@acme.com",
    "branding": {
      "name": "Acme Print",
      "logo_url": "https://acmeprint.com/logo.svg",
      "primary_color": "#1a365d",
      "accent_color": "#2563eb",
      "hide_footer": false
    },
    "detail_level": "comprehensive",
    "summary_page": "prepend"
  }'

{
  "reports": [
    { "format": "json", "url": null, "token": null, "expires_at": null,
      "data": { "summary": { "error_count": 2 }, "findings": [ ... ] },
      "content_type": "application/json" },
    { "format": "annotated_pdf", "token": "rpt_01HXY...",
      "expires_at": "2026-04-26T10:30:00Z",
      "url": "https://reports.lintpdf.com/r/rpt_01HXY....pdf",
      "data": null, "content_type": null },
    { "format": "html", "token": "rpt_01HXZ...",
      "expires_at": "2026-04-26T10:30:00Z",
      "url": "https://reports.lintpdf.com/r/rpt_01HXZ...",
      "data": null, "content_type": null }
  ]
}

Generate-reports request fields

Generate-reports response fields

Idempotency-Key (optional)

Send the Idempotency-Key request header (max 255 characters) to make mints safe to retry. The engine derives each token as sha256(tenant_id + idempotency_key + format) and reuses the stored artifact instead of regenerating it when the same key recurs. Keys are scoped per tenant — a shared key will never collide with another tenant's reports.

For a job-submit-time brand override using the three-way enum ("anonymous" | "lintpdf" | uuid) use the brand field on POST /api/v1/jobs. The reports endpoint takes the richer BrandingOverride object form so per-report tweaks (logo URL, hide footer, etc.) survive.

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

{
  "reports": [
    {
      "token": "rpt_01HXY...",
      "format": "pdf",
      "expires_at": "2026-04-26T10:30:00Z",
      "created_at": "2026-04-12T10:30:00Z",
      "accessed_count": 3
    }
  ]
}

curl -X DELETE https://api.lintpdf.com/api/v1/jobs/.../reports/rpt_01HXY... \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 204 No Content

Public (token-gated) surfaces

The following endpoints require no authentication. Access is gated by possession of the token alone — treat them like signed URLs.

curl https://reports.lintpdf.com/r/rpt_01HXY...

200 OK
Content-Type: text/html

curl -o report.pdf https://reports.lintpdf.com/r/rpt_01HXY....pdf?download=1

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="report.pdf"

curl https://api.lintpdf.com/api/v1/reports/tokens/rpt_01HXY...

{
  "job_id": "d4e5f6a7-...",
  "tenant_id": "...",
  "file_name": "brochure.pdf",
  "email_required": true
}

curl https://api.lintpdf.com/api/v1/reports/tokens/rpt_01HXY.../findings

{
  "findings": [
    {
      "inspection_id": "font.not_embedded",
      "severity": "error",
      "message": "Font 'Helvetica' is not embedded",
      "page_num": 1,
      "details": null,
      "source": "engine",
      "category": "fonts",
      "bbox": [72.0, 720.0, 540.0, 740.0],
      "object_id": "Font12",
      "object_type": "font"
    }
  ]
}

Public viewer surfaces

Every authenticated viewer route has an unauthenticated parallel rooted at /api/v1/viewer/public/{token}/*. The token carries the frozen brand, so GET .../config emits the same branding block regardless of later tenant setting changes.

curl https://api.lintpdf.com/api/v1/viewer/public/rpt_01HXY.../pages

{
  "job_id": "d4e5f6a7-...",
  "page_count": 1,
  "pages": [ { "page_num": 1, "width_pts": 595.28, "height_pts": 841.89, ... } ]
}

Parallel public routes exist for: tile, info, separations, channel, tac-heatmap, sample, layers, config, and verdict (read-only GET).

Bulk report-mint

When a client has completed many independent jobs and needs share links for all of them, the single-endpoint approach is one HTTP round trip per job. At bulk scale (hundreds of jobs) that N-request storm is a common source of dropped mints.POST /api/v1/reports:batchMintcollapses the fan-out into a single request. Minted tokens are byte-identical to the single-endpoint output; the only behavioral difference is that advanced per-call knobs (universal overrides envelope, inline returns, idempotency-key) live only on the single endpoint. Hard-capped at 500 job_ids per call.

curl -X POST https://api.lintpdf.com/api/v1/reports:batchMint \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "job_ids": ["d4e5f6a7-...", "a1b2c3d4-...", "e5f6a7b8-..."],
    "formats": ["html", "pdf", "json"],
    "expiry_days": 7,
    "allow_annotations": false,
    "require_visitor_email": false
  }'

{
  "results": [
    { "job_id": "d4e5f6a7-...", "status": "ok",
      "reports": [
        { "format": "html", "token": "rpt_01HXY...",
          "url": "https://reports.lintpdf.com/r/rpt_01HXY...",
          "viewer_url": "https://app.lintpdf.com/view/rpt_01HXY...",
          "expires_at": "2026-04-28T10:30:00Z" },
        { "format": "pdf", "token": "rpt_01HXZ...", ... },
        { "format": "json", "token": "rpt_01HXA...", ... }
      ]
    },
    { "job_id": "a1b2c3d4-...", "status": "failed",
      "error": "404: Job not found" }
  ],
  "summary": { "ok": 1, "failed": 1 }
}

Webhooks & check-name registry

Webhooks deliver real-time job events to your HTTPS endpoint. Every delivery is signed with X-LintPDF-Signature using HMAC-SHA256, hex-encoded, and prefixed with sha256=. Private-IP destinations are blocked at registration. Webhooks require the Growth plan or above.

curl -X POST https://api.lintpdf.com/api/v1/webhooks \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/lintpdf",
    "events": ["job.state_changed", "approval.chain.completed"],
    "max_retries": 5,
    "retry_base_delay_seconds": 2,
    "retry_max_delay_seconds": 60,
    "delivery_retention_days": 30,
    "retention_overrides": { "billing.*": 365 }
  }'

{
  "id": "0e7f6c5b-4a3f-4210-9876-543210fedcba",
  "url": "https://your-app.com/webhooks/lintpdf",
  "events": ["job.state_changed", "approval.chain.completed"],
  "is_active": true,
  "created_at": "2026-04-12T10:30:00Z",
  "max_retries": 5,
  "retry_base_delay_seconds": 2,
  "retry_max_delay_seconds": 60,
  "delivery_retention_days": 30,
  "retention_overrides": { "billing.*": 365 }
}

The signing secret is generated server-side at registration and is not returned in the response body. Retrieve it from the dashboard (Webhooks → Endpoint → Reveal secret). Store it alongside the endpoint URL and use it in the signature-validation recipes below.

curl https://api.lintpdf.com/api/v1/webhooks \
  -H "Authorization: Bearer lpdf_live_..."

{
  "webhooks": [
    { "id": "0e7f6c5b-...", "url": "...", "events": [...], "is_active": true,
      "created_at": "2026-04-12T10:30:00Z" }
  ]
}

curl -X PATCH https://api.lintpdf.com/api/v1/webhooks/0e7f6c5b-... \
  -H "Authorization: Bearer lpdf_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

{ "id": "0e7f6c5b-...", "is_active": false, ... }

curl -X DELETE https://api.lintpdf.com/api/v1/webhooks/0e7f6c5b-... \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 204 No Content

curl -X POST https://api.lintpdf.com/api/v1/webhooks/0e7f6c5b-.../test \
  -H "Authorization: Bearer lpdf_live_..."

{
  "success": true,
  "status_code": 200,
  "error": "",
  "event": "test.ping"
}

Events

Event payload — job.completed

{
  "event": "job.completed",
  "job_id": "d4e5f6a7-1234-4567-89ab-cdef01234567",
  "status": "complete",
  "profile_id": "lintpdf-default",
  "duration_ms": 3480,
  "summary": {
    "total_findings": 7,
    "error_count": 1,
    "warning_count": 4,
    "advisory_count": 2,
    "passed": false,
    "page_count": 12,
    "file_size_bytes": 842139
  }
}

Event payload — job.failed

{
  "event": "job.failed",
  "job_id": "d4e5f6a7-...",
  "status": "failed",
  "error": "Unsupported PDF version: 2.1"
}

Request headers

Signature validation — Python

import hmac, hashlib

def valid(body: bytes, header: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={mac}", header)

Signature validation — Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function valid(body: Buffer, header: string, secret: string) {
  const mac = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
  const a = Buffer.from(mac);
  const b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}

Event catalog

The full list of events your endpoint can subscribe to. See the dedicated Webhooks page for delivery semantics, replay, and sample payloads.

Delivery audit + replay

Every dispatched event lands in the webhook_deliveries table with the exact JSON body LintPDF signed. A failed endpoint no longer means a lost event — operators can inspect and replay any past delivery.

curl "https://api.lintpdf.com/api/v1/webhooks/deliveries?success=false&page_size=25" \
  -H "Authorization: Bearer lpdf_live_..."

{
  "deliveries": [
    {
      "id": "...",
      "webhook_id": "...",
      "event": "job.state_changed",
      "url": "https://your-app.com/webhooks/lintpdf",
      "attempt_count": 1,
      "final_status_code": 503,
      "success": false,
      "last_error": "HTTP 503",
      "created_at": "2026-04-18T02:11:00Z",
      "delivered_at": "2026-04-18T02:11:02Z"
    }
  ],
  "total": 1, "page": 1, "page_size": 25
}

curl "https://api.lintpdf.com/api/v1/webhooks/deliveries/..." \
  -H "Authorization: Bearer lpdf_live_..."

{
  "id": "...", "event": "job.state_changed", "success": false,
  "payload": { "reason": "verdict.changed", "job": { "...": "..." } }
}

curl -X POST https://api.lintpdf.com/api/v1/webhooks/deliveries/.../replay \
  -H "Authorization: Bearer lpdf_live_..."

HTTP/1.1 201 Created
{
  "id": "<new-delivery-id>",
  "event": "job.state_changed",
  "attempt_count": 0,
  "success": false,
  "payload": { "...": "same as original" }
}

Check-name registry

Unauthenticated, cache-aggressive endpoint mapping every engine inspection_id to a human-readable name and description. Safe to cache for 24h in your client.

curl https://api.lintpdf.com/api/v1/check-names

{
  "font.not_embedded": {
    "name": "Font Not Embedded",
    "description": "Font is referenced but not embedded in the PDF"
  },
  "image.low_resolution": {
    "name": "Low-Resolution Image",
    "description": "Raster image falls below the profile's effective DPI threshold"
  }
}

AI-Explain

Generate a human-readable explanation for a finding via Claude Haiku 4.5. Explanations are cached on the finding row so repeated calls hit the cache for free. Cost-cap exceeded returns HTTP 402 — preflight + reports keep working, only the LLM features pause until the next monthly reset (or a higher cap).

POST /api/v1/jobs/abc/findings/xyz/explain
Authorization: Bearer lpdf_live_...

{
  "finding_id": "xyz",
  "explanation": "This font is not embedded; the press will substitute Helvetica.",
  "model": "claude-haiku-4-5",
  "cached": false,
  "cost_cents": 0.04
}

Cost-cap behavior (Q-C5)

When the tenant's monthly LLM cost cap is exhausted, this endpoint returns 402 with a structured detail. The dashboard and SDK surface that as a “raise the cap” CTA.

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "detail": "Cost cap exceeded — raise the cap in Account → Billing.",
  "used_cents": 9987,
  "monthly_cap_cents": 10000
}

EPM candidacy verdict

EPM (Extended Print Mode) is HP's CMY-only press path that skips the K plate for throughput. The engine scores every completed job against the 16 LPDF_EPM_*_REJECT codes plus the legacy LPDF_EPM_001..018 set and surfaces a tier verdict with rejection drivers, advisories, and an IndiChrome-substrate upsell hint.

GET /api/v1/jobs/abc/epm
Authorization: Bearer lpdf_live_...

{
  "job_id": "abc",
  "tier": "marginal",
  "rejection_drivers": ["LPDF_EPM_BLEED_REJECT"],
  "advisories": ["LPDF_EPM_TRAPPING_REJECT"],
  "recommends_indichrome": false,
  "legacy_codes_fired": [],
  "epm_findings_count": 2
}

Tiers

Inline on JobResponse

The verdict is also surfaced inline on the single-job GET /api/v1/jobs/{id} response under epm_verdict. List endpoints (GET /api/v1/jobs) leave it null — scoring per row is skipped to keep list latency cheap.

GET /api/v1/jobs/abc

{
  "job_id": "abc",
  "epm_verdict": { "tier": "marginal", … },
  "decisions_count": 1,
  …
}

Decisions audit (V-05)

Operator decisions on jobs and findings are stored in a tenant-scoped append-only audit table. Decisions never delete — revoke stamps revoked_at / revoked_by_user_id / revoked_reason so audit replays stay correct after operators change their minds.

GET /api/v1/jobs/abc/decisions?include_revoked=false&limit=200
Authorization: Bearer lpdf_live_...

{
  "decisions": [
    {
      "id": "d1",
      "job_id": "abc",
      "finding_id": null,
      "decision_type": "approve",
      "decided_by_user_id": "u1",
      "source": "dashboard",
      "decided_at": "2026-04-27T12:00:00Z",
      "is_active": true
    }
  ],
  "count": 1
}

POST /api/v1/jobs/abc/decisions
Content-Type: application/json
Authorization: Bearer lpdf_live_...

{
  "decision_type": "approve",
  "decided_by_user_id": "u1",
  "source": "api",
  "notes": "Approved after operator review."
}

{
  "id": "d1",
  "decision_type": "approve",
  "decided_by_user_id": "u1",
  "source": "api",
  "is_active": true,
  ...
}

POST /api/v1/jobs/abc/findings/xyz/decisions
Content-Type: application/json
Authorization: Bearer lpdf_live_...

{
  "decision_type": "waive",
  "decided_by_user_id": "u1",
  "source": "api",
  "notes": "Customer accepts the risk."
}

{ "id": "d2", "finding_id": "xyz", "decision_type": "waive", … }

POST /api/v1/jobs/abc/decisions/d1/revoke
Content-Type: application/json
Authorization: Bearer lpdf_live_...

{ "revoked_by_user_id": "u2", "revoked_reason": "Mistake" }

{
  "id": "d1",
  "is_active": false,
  "revoked_at": "2026-04-27T12:30:00Z",
  "revoked_by_user_id": "u2",
  "revoked_reason": "Mistake"
}

Effective decision on findings

The latest non-revoked decision per finding is also surfaced on each FindingResponse as effective_decision — a minimal projection so dashboards can render the verdict chip without a second fetch.

Workflows

A Workflow pins a profile + brand spec + per-call ToggleOverride defaults under a single name so jobs can be submitted with a single named handle. Workflows replace the legacy /api/v1/endpoints custom-endpoint surface (Phase 0.7 unified-config substrate).

GET /api/v1/workflows
Authorization: Bearer lpdf_live_...

{
  "workflows": [
    {
      "id": "w1",
      "name": "Coated stock",
      "profile_id": "lintpdf-default",
      "brand_spec_id": null,
      "created_at": "2026-04-20T12:00:00Z"
    }
  ]
}

POST /api/v1/workflows
Content-Type: application/json
Authorization: Bearer lpdf_live_...

{
  "name": "Uncoated stock",
  "profile_id": "lintpdf-default",
  "brand_spec_id": null
}

{ "id": "w2", "name": "Uncoated stock", "profile_id": "lintpdf-default" }

PATCH /api/v1/workflows/w2
Content-Type: application/json
Authorization: Bearer lpdf_live_...

{ "name": "Renamed" }

{ "id": "w2", "name": "Renamed", … }

DELETE /api/v1/workflows/w2
Authorization: Bearer lpdf_live_...

HTTP/1.1 204 No Content

Enum appendix

preflight_source

external_format

brand

branding-defaults mode

severity

verdict

The viewer config also carries verdict_mode (auto | manual | off) which governs whether a pass/fail comes from the engine's summary or a manual reviewer action.

source (finding provenance)

BrandProfile profile_type

Finding object_type

Preflight profiles (as opposed to brand profiles) don't use a string enum — the API exposes a boolean is_builtin on ProfileSummaryResponse to distinguish LintPDF-shipped profiles from tenant-owned customs.

EpmTier

decision_type

decision_source