API Reference

REST API

For traditional automation: scripts, CI/CD jobs, dashboards, and webhook receivers.

• JSON over HTTPS
• Pagination via DRF page parameters
• Server-side filters per resource
• Same auth model as the web UI

MCP Server

For AI agents (Claude, Cursor, Windsurf, the Anthropic SDK). Streamable HTTP transport, 16 tools, no glue code.

• Native tool-use without writing wrappers
• Targets, scans, recon data, vulns, OSINT
• Cross-tool chaining with the SAT phishing engine
• See the full MCP reference →

HailBytes ASM

Generate API keys from Administration › API Keys › Add Key. Keys are SHA-256 hashed at rest and shown only once at creation.

curl https://your-asm-host/api/listTargets/ \
  -H "X-API-Key: $HAILBYTES_ASM_KEY"

Keys can have expiration dates. Expired or deactivated keys are rejected automatically. Browser sessions also work for endpoints called from the UI; CSRF token required when not using X-API-Key.

HailBytes SAT

Generate API keys from Account Settings › API Key. SAT preserves the upstream phishing-engine REST contract for backward compatibility.

curl https://your-sat-host/api/campaigns/ \
  -H "Authorization: Bearer $HAILBYTES_SAT_KEY"

The header Authorization: Bearer <key> is the documented form. The legacy ?api_key= query parameter still works but is discouraged because it leaks into request logs.

Add a target and start a scan

# Add the target to a project
curl -X POST https://your-asm-host/api/add/target/ \
  -H "X-API-Key: $ASM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "domain_name": "example.com",
        "slug": "client-pentest",
        "organization": "Example Corp"
      }'

# domain_id comes back in the response. Start a scan from
# the UI, or initiate a subscan via the API.

Pull only Critical vulns from the latest scan

curl "https://your-asm-host/api/listVulnerability/?\
project=client-pentest&severity=4" \
  -H "X-API-Key: $ASM_KEY" \
  | jq '.results[] | {name, http_url, cvss_score}'

Re-screenshot a set of subdomains

curl -X POST https://your-asm-host/api/action/initiate/subtask/ \
  -H "X-API-Key: $ASM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "subdomain_ids": [1523, 1524, 1525],
        "tasks": ["screenshot", "fetch_url"]
      }'

Wait for a scan to finish in CI

SCAN_ID=156
until curl -s "https://your-asm-host/api/scan_status/?\
project=client-pentest" \
  -H "X-API-Key: $ASM_KEY" \
  | jq -e ".scans.completed[] | select(.id==$SCAN_ID)" \
  > /dev/null
do sleep 30; done

Schedule a campaign

curl -X POST https://your-sat-host/api/campaigns/ \
  -H "Authorization: Bearer $SAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Q2 Baseline",
        "template": {"name": "Office365 MFA Reset"},
        "page":     {"name": "Office365 Login"},
        "smtp":     {"name": "SES Production"},
        "groups":   [{"name": "Engineering"}],
        "launch_date":  "2026-06-01T13:00:00Z",
        "send_by_date": "2026-06-08T17:00:00Z"
      }'

Pull users who clicked but didn’t pass the quiz

curl "https://your-sat-host/api/quiz-results/?\
campaign_id=42&passed=false" \
  -H "Authorization: Bearer $SAT_KEY" \
  | jq '.results[] | {email, score, attempted_at}'

Stream audit log to a SIEM

# Pull only events newer than the last cursor
curl "https://your-sat-host/api/audit/?since=$LAST_TS&format=json" \
  -H "Authorization: Bearer $SAT_KEY" \
  | curl -X POST https://siem.example.com/_bulk \
      -H "Content-Type: application/x-ndjson" \
      --data-binary @-

Generate a certificate PDF

curl -L "https://your-sat-host/api/certificates/?\
recipient=user@example.com&campaign_id=42" \
  -H "Authorization: Bearer $SAT_KEY" \
  -o certificate.pdf

HailBytes ASM events

• scan.started
• scan.completed
• scan.failed
• vulnerability.discovered (filtered by min severity)
• subdomain.new (delta vs previous scan)

Configure under Notifications. Slack, Discord, Telegram, Lark, and generic JSON-POST destinations supported.

HailBytes SAT events

• campaign.launched
• campaign.completed
• email.sent / email.opened
• link.clicked
• credentials.submitted
• email.reported (user reported phishing)
• training.completed