REST API
Bearer-token API for starting Site Audits, Conversion Audits, and Content Quality Audits, and reading status. Available on Business and Agency plans.
Setup
Create an API key in Dashboard → Integrations. The full key is shown once — store it in your secrets manager. Creating a key requires Business or Agency at creation time; the key itself isn't re-checked against your current plan on every request.
- Create an API key
- Export it in your shell or CI secrets as WPAQ_API_KEY
- Send Authorization: Bearer on every request below
The API covers create + poll for all three products. Findings detail, screenshots, exports, share links, re-audit, and comparisons are dashboard-only (browser session), not part of this key-based API — see What's not in the API.
Authentication
Every request needs your API key in the Authorization header.
export WPAQ_API_KEY="wpaq_..."
curl -sS -X POST "https://wpaq.com/api/v1/site-audits" \
-H "Authorization: Bearer $WPAQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Rate limits
Independent of monthly plan quota, requests are throttled per hour.
POST /api/v1/site-audits per account (also capped at 8/hr per source IP — matters for shared CI runners).
POST /api/v1/conversion-audits and /quality-audits per account, Business/Agency.
Same two endpoints on a plan without paid access (a guest fingerprint or Starter key, where applicable).
Repeated 429s from the same source extend the window (escalating backoff) — back off instead of retrying immediately. GET polling isn't rate-limited beyond normal abuse protection.
Start a Site Audit
Submit a public URL. The response includes an audit id to poll. Business and Agency plans run full-depth Site Audits with deeper browser checks. You don't need to own the URL.
/api/v1/site-auditsRequired body field: url. On Business and Agency you may also send crawl_mode and url_list to control how pages are discovered.
{
"url": "https://example.com",
"crawl_mode": "bfs",
"url_list": ["https://example.com/page-a"]
}- crawl_mode
bfs(default, follow links),sitemap_only(XML sitemap only), orurl_list(only the URLs you pass, max 200 — Business/Agency only)- Limits
- Pages per Site Audit and monthly Site Audit count follow your plan. A site you haven't DNS-verified (including any third-party site) is capped around 10 pages (Starter/Business) or 100 pages (Agency) — see Auditing sites you don't own.
- Deduplication
- Auditing a host you already audited in the last 6 hours returns the existing scan instead of a new crawl (
"reused_report": truein the response).
{
"id": "b5659908-...",
"url": "https://example.com",
"hostname": "example.com",
"status": "completed",
"scan_type": "full",
"pages_discovered": 12,
"pages_scanned": 12,
"pages_failed": 0,
"overall_score": 91,
"technical_score": 92,
"seo_score": 88,
"performance_score": 95,
"accessibility_score": 97,
"security_score": 82,
"progress": { "step": "done" },
"error_message": null,
"created_at": "2026-09-10T12:00:00Z",
"completed_at": "2026-09-10T12:02:14Z",
"screenshots": [],
"site_screenshot": null,
"reused_report": false
}status is one of queued, running, completed, completed_with_warnings, or failed. Warnings mean some pages were blocked, timed out, or hit a plan limit — still usable, just check for skipped pages. Score fields are null until the run finishes.
Poll Site Audit status
Repeat until status is completed, completed_with_warnings, or failed.
/api/v1/site-audits/{audit_id}AUDIT_ID="paste-from-create-response"
curl -sS "https://wpaq.com/api/v1/site-audits/$AUDIT_ID" \
-H "Authorization: Bearer $WPAQ_API_KEY"Open https://wpaq.com/site-audit/{id} in a browser for the full report — findings, screenshots, export, and share aren't in this API.
Start a Conversion Audit
Submit a landing page URL plus questionnaire answers. Charges AI credits the same as starting one from the dashboard.
/api/v1/conversion-auditsRequired body fields: url and answers — a map of questionnaire question ids to { "selected": [...], "other": "..." }. Fetch the current question set from GET /api/conversion-audits/questionnaire (no auth required).
{
"url": "https://example.com/landing",
"answers": {
"primary_goal": { "selected": ["signup"], "other": "" }
}
}Cost: 10 AI credits if the target is a site you've DNS-verified ownership of, 20 otherwise (any third-party site included) — returns 402 if you're short. See Auditing sites you don't own.
{
"id": "9f2c...",
"type": "convert",
"url": "https://example.com/landing",
"hostname": "example.com",
"status": "completed",
"website_id": "a1b2...",
"website_verified": true,
"overall_score": 74,
"credits_charged": 10,
"questionnaire": { "primary_goal": { "selected": ["signup"], "other": "" } },
"error_message": null,
"created_at": "2026-09-10T12:00:00Z",
"completed_at": "2026-09-10T12:01:40Z",
"has_screenshot": true,
"report": { "...": "full structured report — omitted from the create response" }
}Poll Conversion Audit status
Repeat until status is completed, completed_with_warnings, or failed.
/api/v1/conversion-audits/{check_id}CHECK_ID="paste-from-create-response"
curl -sS "https://wpaq.com/api/v1/conversion-audits/$CHECK_ID" \
-H "Authorization: Bearer $WPAQ_API_KEY"Start a Content Quality Audit
Submit a single page URL. Charges AI credits the same as starting one from the dashboard.
/api/v1/quality-auditsRequired body field: url.
{
"url": "https://example.com/blog/post"
}Cost: same mechanic as Conversion Audit — 10 credits verified, 20 unverified. Response shape mirrors Conversion Audit above ("type": "quality", no questionnaire field).
Poll Content Quality Audit status
Repeat until status is completed, completed_with_warnings, or failed.
/api/v1/quality-audits/{check_id}CHECK_ID="paste-from-create-response"
curl -sS "https://wpaq.com/api/v1/quality-audits/$CHECK_ID" \
-H "Authorization: Bearer $WPAQ_API_KEY"Auditing sites you don't own
You can point any of the three products at any public URL — ownership isn't required. The gate is technical/economic, not a permission check.
- Site Audit — unverified (including any third-party site) caps around 10 pages (Starter/Business) or 100 pages (Agency). Verify ownership with a DNS TXT record to unlock your plan's full crawl limit.
- Conversion Audit / Content Quality Audit — unverified costs 20 AI credits per run instead of 10.
See the Acceptable Use Policy for the actual dos/don'ts — don't bypass logins, CAPTCHAs, or robots.txt; don't use WPAQ to find exploits or overload a host.
What's not in the API
The following are dashboard-only actions, authenticated by browser session cookie — a request with Authorization: Bearer ... against these gets 401:
- Findings detail, screenshots, page-by-page results
- PDF / Excel / Markdown export (Site Audit also has CSV)
- Share links
- Re-audit and audit-to-audit comparison (Site Audit only)
- Conversion Audit visual mockups (dashboard-only, 15 AI credits)
GitHub Action
Gate pull requests or deploys on a live WPAQ Site Audit without writing your own poll loop.
Store your API key as the repository secret WPAQ_API_KEY, then call the composite Action from the public wpaq-public repo. Optional min-score fails the job when the overall score is too low.
- uses: KushalAzza/wpaq-public/actions/scan@v1
with:
api-key: ${{ secrets.WPAQ_API_KEY }}
url: https://example.com
min-score: "70"Full example: wpaq-public examples/github-actions/wpaq-scan.yml. Requires curl and jq on the runner (included on ubuntu-latest). Action source: KushalAzza/wpaq-public/actions/scan. This Action only starts a Site Audit — there's no Conversion/Quality Audit equivalent yet.
Errors
Every error body is {"detail": "human-readable message"}.
Bad request — invalid URL, malformed questionnaire answers, etc.
Missing, invalid, or revoked API key — or a session-only endpoint hit with a Bearer token.
Not enough AI credits for a Conversion/Quality Audit run.
Plan doesn't include the feature — e.g. tried to create a key without Business/Agency (checked at key-creation time, not per request).
Audit/check not found, or it belongs to a different account.
Rate limit or monthly quota hit — see rate limits above. Back off before retrying.