REST API Documentation & Integration
Integrate deterministic perimeter security scanning and compliance auditing directly into your CI/CD pipelines, DevOps deployment workflows, and vendor risk engines.
Authentication & Security
Requests to protected endpoints require an API token sent in the standard HTTP Authorization header. You can generate and rotate your keys inside the Dashboard settings.
Quickstart Request
curl -X POST "https://webdefect.com/api/audit/start" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer wfp_live_your_api_key" \
-d '{
"domain": "example.com",
"scanMode": "standard"
}'Core API Endpoints
Initiate Autonomous Domain Audit
Starts an asynchronous 17-module audit of the requested target domain. Returns an audit ID for polling progress.
{
"domain": "example.com",
"scanMode": "standard" // "standard" | "deep"
}{
"id": "aud_7f9b2c3a-9e20-4281-a83d-3b7c89d2a014",
"domain": "example.com",
"status": "queued",
"startedAt": 1725619200000,
"phasesTotal": 14
}Poll Audit Execution Status & Telemetry
Retrieves real-time execution progress, current inspection module, elapsed milliseconds, and completion percentage.
{
"id": "aud_7f9b2c3a-9e20-4281-a83d-3b7c89d2a014",
"status": "in_progress", // "queued" | "in_progress" | "completed" | "failed"
"currentPhase": "phase_tls_transport",
"percentComplete": 42,
"elapsedMs": 14200,
"phasesCompleted": 6,
"summary": {
"checksExecuted": 182,
"findingsCount": 3
}
}Retrieve Full Cryptographic Findings Report
Fetches the complete audit result including overall numerical score (0-100), letter grade (A+ through F), category breakdown, and CVSS 4.0 findings with raw HTTP proof.
{
"id": "aud_7f9b2c3a-9e20-4281-a83d-3b7c89d2a014",
"domain": "example.com",
"status": "completed",
"score": {
"total": 92,
"grade": "A",
"categories": {
"tls": 95,
"http_security": 88,
"dns_email": 100,
"network": 90
}
},
"findings": [
{
"id": "WD-F-001",
"category": "http_security",
"severity": "medium",
"title": "Content-Security-Policy Lacks frame-ancestors Directive",
"description": "The page can potentially be embedded in unauthorized iframes, enabling UI redressing attacks.",
"cvss": 4.3,
"affectedUrl": "https://example.com/",
"evidence": "X-Frame-Options: SAMEORIGIN present, but CSP frame-ancestors missing."
}
]
}Download Tamper-Evident Board PDF Dossier
Generates and streams a board-ready executive security report in PDF format, complete with cryptographic hash verification.
[Binary PDF Stream (application/pdf)]
Compare Dual Target Security Assessments
Fetches side-by-side security posture metrics, differential score delta, defensive pillar benchmarks, and severity breakdown for two domains.
{
"targetA": {
"domain": "stripe.com",
"score": 96,
"grade": "A+",
"pillars": { "tls": { "score": 100, "status": "pass" }, "dns": { "score": 95, "status": "pass" } }
},
"targetB": {
"domain": "adyen.com",
"score": 92,
"grade": "A",
"pillars": { "tls": { "score": 95, "status": "pass" }, "dns": { "score": 90, "status": "pass" } }
},
"delta": 4,
"lead": "stripe.com"
}Retrieve Quota & Scan Allowance
Returns your current audit quota, completed scans, remaining allowances, and subscription tier status.
{
"used": 1,
"limit": 3,
"remaining": 2,
"isAuthenticated": true,
"subscriptionStatus": "free" // "free" | "premium"
}Continuous Integration & PR Gating
Integrate WebDefect with GitHub Actions or GitLab CI to fail builds whenever an engineer introduces missing security headers, weak TLS ciphers, or dangling subdomains.
# .github/workflows/perimeter-audit.yml
name: Perimeter Security Audit
on: [deployment_status]
jobs:
wfp_audit:
runs-on: ubuntu-latest
steps:
- name: Trigger WebDefect Scan
run: |
AUDIT_ID=$(curl -s -X POST "https://webdefect.com/api/audit/start" \
-H "Authorization: Bearer ${{ secrets.WFP_API_KEY }}" \
-H "Content-Type: application/json" \
-d '{"domain":"staging.yourcompany.com"}' | jq -r '.id')
echo "Audit triggered: $AUDIT_ID"Ready to automate your attack surface monitoring?
Generate an API key in your account dashboard to get started with 50 free API credits per month.