Skip to main content
WP HealthKit

Scan API

Deterministic scans in a single request — ZIP or WordPress.org slug in, grade and findings out. No queue, no AI engines, typically seconds.

When to use it

The Scan API is the wholesale/fast path: the deterministic scanner set without AI reasoning, Playground probes or the Fix Plan. It is what hosts, marketplaces and directory integrations run on every upload. For a full audit — AI taint analysis, exploit chains, Fix Plan — use POST /api/v1/audit instead.

Results are cached by the artifact's SHA-256 plus profile. Re-scanning the same ZIP returns the stored result with cached: true and costs a fraction of a full scan (it still counts once against your monthly quota).

Authentication

Create a scan key in Settings → API keys, or with POST /api/settings/scan-keys. Send it as a Bearer token:

curl -X POST https://wphealthkit.com/api/v1/scan \
  -H "Authorization: Bearer whk_live_your_scan_key" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "contact-form-7", "profile": "core" }'

Scan keys are separate from normal API keys: a free_attribution key works on a free account, and requires an app name + URL for the "Powered by WP HealthKit" attribution. Platform/Enterprise API keys are also accepted and get the developer tier.

Input

Two content types — JSON for a WordPress.org plugin, multipart for your own ZIP (20 MB max):

# WordPress.org slug (optional pinned version)
{ "slug": "woocommerce", "version": "9.4.1", "profile": "core" }

# ZIP upload
curl -X POST https://wphealthkit.com/api/v1/scan \
  -H "Authorization: Bearer whk_live_your_scan_key" \
  -F "plugin=@my-plugin.zip" \
  -F "profile=core"

Profiles: core runs the source scanners and free supply-chain intel. full-static adds PHPCS, PHPStan, Semgrep and Psalm (platform tier). Intel-gated scanners (Wordfence, WPScan, Socket) are never served through this endpoint.

Response

{
  "data": {
    "ok": true,
    "cached": false,
    "profile": "core",
    "grade": "B",

    "overallRisk": "MEDIUM",
    "plugin": { "slug": "my-plugin", "name": "My Plugin", "version": "1.2.0", "type": "plugin" },
    "counts": { "critical": 0, "high": 1, "medium": 3, "low": 4, "info": 2, "total": 10 },
    "fixableCount": 6,
    "findings": [
      {
        "id": "rest-auth-1",
        "severity": "HIGH",
        "category": "rest-auth",
        "title": "REST route has no permission_callback",
        "location": "includes/api.php:42",
        "description": "...",
        "remediation": "...",
        "reference": "..."
      }
    ],
    "badgeUrl": "https://wphealthkit.com/api/badge/by-slug/my-plugin",
    "aiUpgrade": { "available": true, "message": "...", "url": "https://wphealthkit.com/upload" },
    "scanDurationMs": 1840
  },
  "error": null,
  "meta": { "timestamp": "2026-11-18T12:00:00.000Z" }
}

scannersRun (also in the response) reports how many scanners the profile ran. A missing scanner means it was not part of the profile, not that it passed silently.

Tiers & limits

Key tierScans / monthRate limitProfiles
free_attribution100 / month2 / mincore
developer2,000 / month10 / mincore
platform25,000 / month60 / mincore, full-static

A per-IP backstop (120 requests/minute) sits in front of key quotas to stop key farming. Failed scans do not consume quota; exhausted quota returns 429.

Create a scan key

Free attribution keys need an app name and URL; paid tiers unlock higher quotas.

Open Settings