Skip to content

Start and read WordPress scans

Start a WP PerformanceShield scan on a site through the API, wait for it to finish and read the score, findings and vulnerabilities.

This guide shows how to start a WordPress security scan on one site with the API, wait for it and read the result. It uses the same operations as the panel.

  • An API key with the scope wpscan:read to read results and wpscan:write to start a scan (scopes). The key never does more than its user: a reseller or client reaches only the sites of their own accounts.
  • The site id. List the sites of an account with GET /api/v1/accounts/{account_id}/sites and take the id of the WordPress site.
  • A server whose agent can scan. If it cannot, the summary says "supported": false and starting a scan answers 409 wpscan_unsupported_agent.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"

POST /api/v1/sites/{id}/wpscan/scans queues a scan and answers 202 at once; the scan runs later on the server. The body is optional: mode is full (the default: integrity checks plus the malware checks over every file) or integrity (the lighter daily check).

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/scans" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode": "full"}'
{
  "queued": true,
  "scan": {
    "id": "7c7c7c7c-1111-4222-8333-444455556666",
    "site_id": "6b6b6b6b-1111-4222-8333-444455556666",
    "mode": "full",
    "reason": "on_demand",
    "state": "queued",
    "requested_at": "2026-11-14T10:02:11Z"
  }
}

Keep scan.id:

export SCAN_ID="7c7c7c7c-1111-4222-8333-444455556666"

Only one scan runs at a time on a server, so a queued scan can wait for its turn. Send an Idempotency-Key so a retry does not queue a second scan.

GET /api/v1/wpscan/scans/{id} returns the scan and, once it has finished, its report. The scan moves through queued, delivering and running to an end state: complete, partial (finished with a partial result), failed or cancelled. Poll every few seconds, or every minute for a large site.

until state=$(curl -fsS "$PLUSPANEL_URL/api/v1/wpscan/scans/$SCAN_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" | jq -r .scan.state) \
  && case "$state" in complete|partial|failed|cancelled) true ;; *) false ;; esac; do
  sleep 10
done
echo "$state"

The fields worth knowing in scan:

  • score (0–100) and grade (A to F), set when the scan ends; null and empty before that.
  • findings_total and vulnerabilities_total: what the scan found.
  • started_at and finished_at.
  • error and error_code when the state is failed.

The scan history of a site is GET /api/v1/sites/{id}/wpscan/scans (newest first; limit and before, the requested_at of the last scan you got, page through it).

GET /api/v1/sites/{id}/wpscan is the current picture of the site: the score is computed over the items that are open now, so it changes when you fix or ignore something.

curl -fsS "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  | jq '{scored, score, grade, scanned_at, open_findings, open_vulnerabilities, running: .running.state}'
{
  "scored": true,
  "score": 82,
  "grade": "B",
  "scanned_at": "2026-11-14T10:04:40Z",
  "open_findings": { "high": 1, "low": 2 },
  "open_vulnerabilities": { "critical": 1 },
  "running": null
}
  • scored is false and score is null until a scan has completely finished.
  • open_findings and open_vulnerabilities count the open items by severity (info, low, medium, high, critical).
  • last_scan is the latest finished scan, running the one queued or in flight, if any.
  • quarantined and quarantined_bytes describe the site’s quarantine; settings holds the three automatic-fix switches.
  • feed.attribution and the attribution of the vulnerabilities answer carry notices that you must show next to the vulnerability records if you display them in your own tool.

GET /api/v1/sites/{id}/wpscan/findings lists what the scan found in the site’s files and database, most severe first. Filters: state (open, resolved, quarantined, ignored), category and severity (the minimum severity).

curl -fsS -G "$PLUSPANEL_URL/api/v1/sites/$SITE_ID/wpscan/findings" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" \
  --data-urlencode "state=open" --data-urlencode "severity=medium" \
  | jq '.items[] | {id, severity, category, path, component}'

A finding has an id, a severity, a category, the path of the file, the component it belongs to (kind core, plugin or theme, with slug and version), a state and two flags, quarantinable and reinstallable, that say which fixes apply.

GET /api/v1/sites/{id}/wpscan/vulnerabilities lists the known vulnerabilities of the installed core, plugins and themes, with title, severity, cvss, cve, installed_version, fixed_in and state (open, fixed, ignored). It takes the filter state.

The same group of operations also fixes things: update a component, quarantine or reinstall files, ignore an item and change the automatic-fix settings. These need wpscan:write; see the API reference under wpscan.

Status Code Meaning
401 invalid_api_key The key is missing, expired or revoked.
403 The key has no wpscan scope, or the user may not use the site.
404 The site or scan does not exist or is not visible to you.
409 edition_limit_reached Free edition: one on-demand scan per site per UTC day. The answer’s limit is wpscan_on_demand_daily.
429 wpscan_rate_limited Pro and Enterprise: one on-demand scan per site every 10 minutes. Retry-After says when to try again.
409 wpscan_unsupported_agent The server’s agent does not support scanning.

Errors are problem details: branch on code.

No webhook event is sent when a scan finishes: poll the scan as in step 2. Alerts that your alert rules raise are sent as alert.firing and alert.resolved (event list).