Authentication Audits Reports Site Monitoring Compliance WP-CLI GitHub Action Rate Limits

API Documentation

Programmatically audit WordPress plugins, monitor sites, and generate reports.

Authentication

All API requests require a Bearer token. Generate an API key in Settings → API Keys.

curl -X POST https://wphealthkit.com/api/agency/audits \
  -H "Authorization: Bearer whk_live_your_api_key" \
  -F "[email protected]"

API keys use the whk_live_ prefix. Keys are hashed on our server — the full key is shown only once at creation.

Audits

POST/api/agency/auditsPro+

Audit a single plugin or theme ZIP file. Returns the audit result with risk rating, finding counts, and report URL.

Request

curl -X POST https://wphealthkit.com/api/agency/audits \
  -H "Authorization: Bearer whk_live_..." \
  -F "[email protected]" \
  -F "agency_name=My Agency" \
  -F "agency_color=#ff6600"

Response

{
  "id": "uuid",
  "pluginName": "My Plugin",
  "pluginVersion": "1.2.3",
  "overallRisk": "HIGH",
  "findingsCount": 12,
  "criticalCount": 0,
  "highCount": 3,
  "reportUrl": "https://wphealthkit.com/results/uuid",
  "pdfUrl": "https://wphealthkit.com/api/reports/uuid/pdf"
}

POST/api/agency/bulkAgency

Audit up to 10 plugins in a single request. Each plugin is processed sequentially.

Request

curl -X POST https://wphealthkit.com/api/agency/bulk \
  -H "Authorization: Bearer whk_live_..." \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Response

{
  "results": [
    { "pluginName": "Plugin 1", "overallRisk": "LOW", "status": "success" },
    { "pluginName": "Plugin 2", "overallRisk": "HIGH", "status": "success" }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}

Reports

GET/api/reports/{id}Free+

Fetch a full audit report by ID. Returns the complete report with findings, executive summary, and metadata.

Request

curl https://wphealthkit.com/api/reports/uuid \
  -H "Authorization: Bearer whk_live_..."

Response

{
  "pluginName": "My Plugin",
  "overallRisk": "HIGH",
  "findings": [...],
  "executiveSummary": "...",
  "codingStandardsScore": 85,
  "phpCompatibility": { "highestPhpRequired": "8.0", ... }
}

GET/api/reports/{id}/pdfFree+

Download the audit report as a branded PDF. Supports white-label branding via query parameters.

Request

curl "https://wphealthkit.com/api/reports/uuid/pdf?agency=MyAgency&color=%2316a34a" \
  -H "Authorization: Bearer whk_live_..." \
  -o report.pdf

Response

Binary PDF file

Site Monitoring

Connect WordPress sites via the companion plugin for continuous monitoring. The companion authenticates with a site token (separate from API keys). Learn more about site monitoring.

Get started quickly by downloading the companion plugin:

Download Companion Plugin

GET/api/sitesPro+

List all connected WordPress sites with health scores, plugin counts, and connection status.

Request

curl https://wphealthkit.com/api/sites \
  -H "Authorization: Bearer whk_live_..."

Response

{
  "sites": [
    { "id": "uuid", "name": "Client Site", "url": "https://example.com",
      "status": "connected", "health_score": 72, "total_plugins": 18, "critical_issues": 0 }
  ],
  "limits": { "used": 1, "max": 50 },
  "tier": "agency"
}

POST/api/sitesPro+

Request

curl -X POST https://wphealthkit.com/api/sites \
  -H "Authorization: Bearer whk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Client Site", "url": "https://example.com"}'

Response

{
  "site": { "id": "uuid", "name": "My Client Site", "url": "https://example.com" },
  "siteToken": "site_abc123...",
  "installInstructions": { "step1": "Install companion plugin", ... }
}

GET/api/sites/{id}Pro+

Full site detail: all plugins with ratings, health score, and activity log.

Request

curl https://wphealthkit.com/api/sites/uuid \
  -H "Authorization: Bearer whk_live_..."

Response

{
  "site": { "name": "Client Site", "healthScore": 72, ... },
  "plugins": [{ "slug": "woocommerce", "version": "9.6.0", "overall_risk": "LOW" }],
  "events": [{ "event_type": "plugin_updated", "message": "WooCommerce updated" }],
  "summary": { "totalPlugins": 18, "audited": 15, "criticalIssues": 0 }
}

POST/api/sites/{id}/auditPro+

Trigger audits for all unaudited or recently-updated plugins. Fetches from wp.org automatically.

Request

curl -X POST https://wphealthkit.com/api/sites/uuid/audit \
  -H "Authorization: Bearer whk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"source": "api"}'

Response

{
  "message": "5 plugins audited",
  "results": [{ "slug": "my-plugin", "success": true, "overallRisk": "MEDIUM" }],
  "remaining": 25
}

POST/api/sites/{id}/check-updatePro+

Pre-update safety check. Returns whether updating a plugin is safe based on CVE data and audit history.

Request

curl -X POST https://wphealthkit.com/api/sites/uuid/check-update \
  -H "Authorization: Bearer site_..." \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-plugin", "currentVersion": "1.0", "newVersion": "1.1"}'

Response

{
  "safe": true,
  "recommendation": "update",
  "warnings": ["v1.1 has not been audited yet"],
  "currentVersion": { "version": "1.0", "risk": "HIGH", "findings": 12 },
  "newVersion": { "version": "1.1", "risk": null, "audited": false }
}

GET/api/sites/{id}/reportPro+

Generate a site-wide security report. Use ?format=html for a branded report suitable for PDF conversion.

Request

curl "https://wphealthkit.com/api/sites/uuid/report?format=json" \
  -H "Authorization: Bearer whk_live_..."

Response

{
  "site": { "name": "Client Site", "healthScore": 72, ... },
  "summary": { "totalPlugins": 18, "audited": 15, "riskCounts": { "CRITICAL": 0, "HIGH": 2 } },
  "plugins": [...],
  "recentActivity": [...]
}

Compliance

GET/api/compliance/cra?auditId={id}Pro+

Generate a CRA Compliance Kit from an existing audit. Returns SECURITY.md, Vulnerability Disclosure Policy, and assessment evidence.

Request

curl https://wphealthkit.com/api/compliance/cra?auditId=uuid \
  -H "Authorization: Bearer whk_live_..."

Response

{
  "securityMd": "# Security Policy\n...",
  "disclosurePolicy": "# Vulnerability Disclosure Policy\n...",
  "assessmentEvidence": { "auditDate": "...", "compliance": true },
  "craCompliant": true
}

WP-CLI

Install the WP-CLI package for command-line audits:

wp package install wphealthkit/wp-cli-audit

# Audit a single plugin
wp healthkit audit my-plugin --api-key=whk_live_...

# Audit all active plugins
wp healthkit audit --all --api-key=whk_live_... --output=table

GitHub Action

Add automated security audits to your CI/CD pipeline:

# .github/workflows/audit.yml
name: Plugin Audit
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: wp-healthkit/audit-action@v1
        with:
          api-key: ${{ secrets.WP_HEALTHKIT_API_KEY }}
          fail-on: HIGH

Rate Limits

Tier	Audits / month	Bulk (per request)	Connected sites	Rate limit
Pro	30	5	1	100 req/day
Agency	200	10	50	1000 req/day

Full documentation

REST API

Full API reference with endpoints, auth, and examples.

CLI

Audit plugins from the terminal with WP-CLI.

MCP Server

Wire WP HealthKit into Claude, Cursor, and AI tools.

Webhooks

Receive on-complete notifications to your endpoint.