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 tier | Scans / month | Rate limit | Profiles |
|---|---|---|---|
free_attribution | 100 / month | 2 / min | core |
developer | 2,000 / month | 10 / min | core |
platform | 25,000 / month | 60 / min | core, 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