REST API

1. Create an API key
2. Export it in your shell or CI secrets as WPAQ_API_KEY
3. 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.

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"}'

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.

{
  "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), or url_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": true in 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.

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.

{
  "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" }
}

{
  "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).

• 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.

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)

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.

Every error body is {"detail": "human-readable message"}.