API Reference

Generate a new 32-byte hex API key. Returns the raw key once.

curl -X POST /api/keys/generate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline"}'

{
  "id": 1,
  "key": "a3f8b2c1d4e5f6a7b8c9...",  // store this — shown once
  "prefix": "a3f8b2c1",
  "name": "CI Pipeline",
  "created_at": "2026-03-16T18:00:00"
}

List your API keys (masked — raw key not returned).

curl /api/keys -H "Authorization: Bearer $JWT"

Revoke an API key immediately.

curl -X DELETE /api/keys/1 -H "Authorization: Bearer $JWT"

Start an async security scan. Returns a scan_id — poll /api/scan/{id} for results.

curl -X POST /api/scan \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://example.com", "scan_types": ["vulnerabilities", "auth", "api", "graphql", "js_asset", "jwt_oauth"], "auth_config": {"cookie_header": "sessionid=abc123; csrftoken=def456", "bearer_token": "eyJhbGciOi...", "forced_browse_paths": ["/dashboard", "/settings"], "role_profiles": [{"name": "user", "role": "user", "cookie_header": "sessionid=user...", "allowed_paths": ["/dashboard"], "restricted_paths": ["/admin"]}, {"name": "admin", "role": "admin", "bearer_token": "eyJ...", "allowed_paths": ["/admin", "/dashboard"]}], "idor_tests": [{"path": "/api/orders/{id}", "source_identity": "user", "own_id": "1001", "foreign_ids": ["1002"]}], "privilege_paths": [{"path": "/admin", "allowed_roles": ["admin"], "denied_roles": ["user"]}]}, "api_config": {"spec_url": "https://example.com/openapi.json", "endpoints": [{"path": "/api/users", "method": "GET", "requires_auth": true}]}, "graphql_config": {"endpoint": "https://example.com/graphql", "requires_auth": true}, "jwt_oauth_config": {"expected_issuer": "https://auth.example.com/", "expected_audience": "api://orders", "openid_config_url": "https://auth.example.com/.well-known/openid-configuration", "client_id": "web-client-prod", "redirect_uris": ["https://app.example.com/callback"]}}'

{"scan_id": 42, "target": "https://example.com", "status": "pending"}

Authenticated scan tips:

• role_profiles let you compare multiple identities in the same scan.
• forced_browse_paths should include high-value authenticated routes such as /dashboard, /billing, or /api/users.
• idor_tests expect a path containing {id} and one or more foreign IDs to try.
• jwt_oauth_config.client_id enables active redirect-uri validation against the authorization endpoint.

Poll scan status and retrieve results when completed.

curl /api/scan/42 -H "X-API-Key: $API_KEY"

{
  "id": 42,
  "target": "https://example.com",
  "status": "completed",       // pending | running | completed | failed
  "overall_score": 78,
  "overall_grade": "C",
  "results": { "ssl": {...}, "headers": {...}, ... },
  "duration_ms": 4321
}

List your recent scans.

curl /api/scans?limit=20 -H "X-API-Key: $API_KEY"

Delete a scan record.

curl -X DELETE /api/scan/42 -H "X-API-Key: $API_KEY"

Create a recurring scan schedule.

curl -X POST /api/scans/schedule \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "frequency": "weekly", "scan_types": ["ssl","headers"]}'

List all your active scan schedules.

curl /api/scans/schedules -H "X-API-Key: $API_KEY"

Remove a scan schedule.

curl -X DELETE /api/scans/schedule/3 -H "X-API-Key: $API_KEY"

Retrieve your notifications (scheduled scan completions). Marks all as read.

curl /api/notifications -H "X-API-Key: $API_KEY"

[
  {
    "id": 5,
    "type": "scan_complete",
    "title": "Scheduled scan completed: example.com",
    "body": "Your weekly scan of example.com finished. Scan ID: 88",
    "scan_id": 88,
    "read": 0,
    "created_at": "2026-03-16T12:00:00"
  }
]

Fast poll for unread notification count.

curl /api/notifications/unread-count -H "X-API-Key: $API_KEY"
{"count": 2}

Register a domain and get verification token.

curl -X POST /api/domains/add \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Trigger verification check (DNS TXT or file).

List your verified domains.

Your scan statistics — totals, avg score, grade distribution.

curl /api/stats -H "X-API-Key: $API_KEY"

Run a Static Application Security Testing (SAST) scan on a GitHub repository. Detects hardcoded secrets, dependency CVEs (via OSV.dev), code vulnerabilities, and misconfigurations. Requires authentication (JWT or API key).

Request body:

{
  "repo_url": "https://github.com/owner/repo",  // required
  "branch":   "main",                            // optional, default "main"
  "token":    "ghp_..."                          // optional — GitHub PAT for private repos
}

Response (immediately):

{
  "scan_id": 42,
  "target":  "https://github.com/owner/repo",
  "status":  "pending",
  "message": "GitHub scan started. Cloning and scanning repository…"
}

Poll GET /api/scan/42 until status == "completed". Results are in results.all_vulnerabilities.

Example with curl:

curl -X POST https://pentestmyapps.com/api/scan/github \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/WebGoat/WebGoat",
    "branch": "main"
  }'

Poll for GitHub scan results. Returns findings once status == "completed".

Finding fields:

{
  "file_path":    "src/app.py",          // relative path in repo
  "line_number":  42,                    // line number (null for file-level findings)
  "severity":     "critical",           // critical / high / medium / low / info
  "category":     "secrets",            // secrets / dependency / code / config
  "title":        "Hardcoded Secret: AWS Access Key",
  "description":  "An AWS Access Key appears hardcoded in the source file.",
  "evidence":     "AWS_KEY = 'AKIA...'", // up to 3 lines of context
  "remediation":  "Remove and rotate the key. Use environment variables.",
  "cwe_id":       "CWE-798",
  "confidence":   "high"                // high / medium / low
}

Categories scanned:

• secrets — AWS/Google/Stripe/Twilio/SendGrid/GitHub/Slack keys, JWT secrets, RSA/SSH private keys, DB passwords, .env files
• dependency — requirements.txt, package.json, Gemfile.lock, go.sum checked against OSV.dev
• code — SQL injection, command injection, insecure deserialization, XSS, path traversal, SSRF, weak crypto, insecure random
• config — DEBUG=True, CORS *, SSL verify=False, hardcoded SECRET_KEY, overly permissive file modes

Download a completed scan report as HTML or JSON.

curl "/api/scan/42/report?format=html" \
  -H "X-API-Key: $API_KEY" \
  -o report.html

Executive PDF report. Requires a plan with PDF reports. The report id printed on the document is stable for the assessment and every download is recorded.

curl "/api/report/42/pdf" \
  -H "X-API-Key: $API_KEY" \
  -o zbreach_report_42.pdf

Control-mapping report for one framework: iso27001 (ISO/IEC 27001:2022 Annex A), soc2, pci (PCI DSS v4.0), nist (SP 800-53 Rev. 5) or owasp. format is json (default) or pdf. Requires a plan with compliance reports. Control references are derived automatically from each finding's CWE, OWASP category, title and module; informational entries are excluded. /api/report/{id}/iso27001, /soc2 and /pci are aliases.

curl "/api/report/42/compliance?framework=iso27001&format=pdf" \
  -H "X-API-Key: $API_KEY" \
  -o zbreach_iso27001_42.pdf