SwarmHawk API

The SwarmHawk API gives you programmatic access to 23 automated security checks plus 3,000+ active nuclei CVE templates — SSL, DNS, CVEs with active exploit confirmation, breach exposure, typosquats, AI threat analysis and more — for any domain. Use it to build security workflows, automate due diligence, or wire SwarmHawk into your AI assistant via MCP.

Quick Start — scan a domain in 30 seconds

# 1. Create a free API key at www.swarmhawk.com → Account → API Keys
# 2. Run your first scan:

curl -X POST https://swarmhawk.com/api/api/v2/scan \
  -H "X-API-Key: swh_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

import requests

API_KEY = "swh_your_key_here"

resp = requests.post(
    "https://swarmhawk.com/api/api/v2/scan",
    headers={"X-API-Key": API_KEY},
    json={"domain": "example.com"}
)
data = resp.json()
print(f"Risk score: {data['risk_score']} · {data['critical']} critical findings")

const res = await fetch("https://swarmhawk.com/api/api/v2/scan", {
  method: "POST",
  headers: {
    "X-API-Key": "swh_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ domain: "example.com" })
});
const data = await res.json();
console.log(`Risk: ${data.risk_score} — ${data.critical} critical`);

Authentication

SwarmHawk uses two authentication methods depending on the endpoint:

API Key format

swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c

Errors & Rate Limits

HTTP status codes

Error response shape

{
  "detail": "Invalid API key"
}

Rate limits

POST /api/v2/scan

Run a full 22-check security scan on any domain. Returns a risk score, detailed findings, and (for paid users) AI threat analysis. Results are saved to your account.

{
  "domain": "example.com",
  "risk_score": 42,
  "critical": 1,
  "warnings": 3,
  "scanned_at": "2025-03-10T09:15:00Z",
  "checks": [
    {
      "check": "ssl",
      "status": "ok",
      "title": "SSL valid for 84 days",
      "detail": "Certificate issued by Let's Encrypt. Expires 2025-06-02.",
      "score_impact": 0
    },
    {
      "check": "breach",
      "status": "critical",
      "title": "4,200 breached accounts found",
      "detail": "Found in LinkedIn 2021 breach. Rotate all credentials.",
      "score_impact": 25
    }
  ]
}

curl -X POST https://swarmhawk.com/api/api/v2/scan \
  -H "X-API-Key: swh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

resp = requests.post(
    "https://swarmhawk.com/api/api/v2/scan",
    headers={"X-API-Key": API_KEY},
    json={"domain": "example.com"}
)
data = resp.json()
# data["risk_score"], data["checks"]

const r = await fetch("https://swarmhawk.com/api/api/v2/scan", {
  method:"POST",
  headers:{"X-API-Key":key,"Content-Type":"application/json"},
  body:JSON.stringify({domain:"example.com"})
});
const d = await r.json();

POST /public-scan

Anonymous scan — no API key required. Returns a subset of checks with some results locked. Use this for demos or embeds. Results are not saved.

{
  "domain": "example.com",
  "risk_score": 42,
  "critical": 1,
  "warnings": 3,
  "locked_count": 8,
  "checks": [/* 7 free checks visible, 8 locked */],
  "scanned_at": "2025-03-10T09:15:00Z"
}

GET /scan/passive

Fast fingerprint scan — detects software stack and checks for known CVEs without a full scan. Response in ~3 seconds. No result saved.

{
  "domain": "example.com",
  "software": [
    {"product": "nginx", "version": "1.18.0"},
    {"product": "WordPress", "version": "6.3.1"}
  ],
  "cves": [
    {"id": "CVE-2023-39320", "cvss": 9.8, "severity": "CRITICAL"}
  ]
}

GET /api/v2/domains

List all domains in your account with their latest risk scores and checks.

{
  "domains": [
    {
      "id": "uuid",
      "domain": "example.com",
      "country": "DE",
      "status": "active",
      "paid": true,
      "risk_score": 42,
      "scanned_at": "2025-03-10T09:15:00Z",
      "checks": [/* latest check array */],
      "scan_history": [{"date":"…","risk":42}]
    }
  ]
}

POST /api/v2/domains

Add a domain to your account and queue a background scan.

{
  "id": "uuid",
  "domain": "mycompany.cz",
  "status": "scanning",
  "message": "Domain added — scan starting now"
}

GET /api/v2/domains/{domain_id}/report

Retrieve the latest full scan report for a domain. Free users see a subset; paid users see all 23 checks including nuclei active CVE validation and AI summary.

{
  "domain": "example.com",
  "risk_score": 42,
  "scanned_at": "2025-03-10T09:15:00Z",
  "paid": true,
  "critical": 1,
  "warnings": 3,
  "informational": 2,
  "locked_count": 0,
  "verified_at": "2026-04-08T10:00:00Z",
  "auth_scanned_at": "2026-04-08T11:00:00Z",
  "auth_scan": { /* authenticated scan result object, null if not run */ },
  "checks": [
    {
      "check": "ssrf",
      "status": "info",
      "confidence": "informational",
      "title": "A10: 3 SSRF surface indicator(s)",
      "detail": "Surface area detected (not confirmed vulnerabilities)…",
      "score_impact": 0
    }
  ]
}

GET /domains/{domain_id}/verify-token

Return the domain ownership verification token for the authenticated user. Use one of the three provided methods to publish the token, then call POST /verify to confirm.

{
  "domain": "example.com",
  "token": "a3f7b2c1d4e5f6a7b8c9d0e1f2a3b4c5",
  "verified_at": null,
  "methods": {
    "dns_txt":   { "value": "swarmhawk-verify=a3f7b2c1…" },
    "well_known":{ "url": "https://example.com/.well-known/swarmhawk-verify.txt" },
    "meta_tag":  { "tag": "<meta name=\"swarmhawk-verify\" content=\"a3f7b2c1…\">" }
  }
}

POST /domains/{domain_id}/verify

Check whether the domain ownership token is present via DNS TXT record, /.well-known/swarmhawk-verify.txt file, or HTML <meta> tag. On success, verified_at is written to the domain and returned in all subsequent report responses.

{ "verified": true, "method": "dns_txt" }

{ "verified": false, "message": "Verification token not found via DNS TXT, .well-known file, or HTML meta tag" }

POST /domains/{domain_id}/scan/authenticated

Run a targeted scan using a real session cookie. Detects cookie security flag gaps (HttpOnly/Secure/SameSite), authenticated page header issues (Cache-Control, clickjacking), and IDOR surface at common API paths. Runs in the background — results are stored in scans.auth_scan and returned in the domain report's auth_scan field.

{
  "cookie":     "sessionid=abc123; csrftoken=xyz456",
  "user_agent": "Mozilla/5.0 …"  // optional
}

{ "status": "scanning", "message": "Authenticated scan started for example.com" }

GET /api/v2/domains/{domain_id}/history

Risk score trend over time — useful for building dashboards or alerting on score increases.

{
  "domain": "example.com",
  "scans": [
    {"risk_score":42,"critical":1,"warnings":3,"scanned_at":"2025-03-10T09:15:00Z"},
    {"risk_score":38,"critical":0,"warnings":4,"scanned_at":"2025-02-10T08:00:00Z"}
  ]
}

GET /api/v2/domains/{domain_id}/nis2

Map scan findings to NIS2 Directive articles. Returns a compliance score and per-article status — suitable as audit evidence for regulators.

{
  "domain": "example.com",
  "risk_score": 42,
  "nis2_score": 71,
  "articles": [
    {
      "article": "Art.21(2)(i)",
      "requirement": "Secure communications",
      "status": "met"
    },
    {
      "article": "Art.21(2)(h)",
      "requirement": "Supply chain security",
      "status": "warning"
    }
  ]
}

POST /intel

Generate an AI-powered threat briefing for your domain portfolio using Claude. Returns a structured briefing with executive summary, critical findings, and remediation priorities.

{
  "text": "## Executive Summary\n\nYour domain portfolio shows...",
  "briefing": "…"
}

POST /api/v2/keys

Create a new API key for your account. Returns all keys including the new one.

{
  "keys": [
    {
      "key": "swh_3f8a2b1c4d5e6f7a8b9c0d1e2f3a4b5c",
      "calls_this_month": 0,
      "limit_per_month": 10,
      "active": true,
      "created_at": "2025-03-10T09:00:00Z"
    }
  ]
}

GET /api/v2/keys

List all API keys and their usage for the current month.

curl https://swarmhawk.com/api/api/v2/keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

DELETE /api/v2/keys/{key}

Revoke an API key immediately. All future requests with this key will be rejected.

{ "revoked": "swh_3f8a2b1c…" }

MCP Server

SwarmHawk exposes a Model Context Protocol server, letting any MCP-compatible AI assistant (Claude, Cursor, Windsurf) call SwarmHawk tools directly from conversation.

Claude Desktop config

{
  "mcpServers": {
    "swarmhawk": {
      "url": "https://swarmhawk.com/api/mcp",
      "headers": { "X-API-Key": "swh_your_key" }
    }
  }
}

Cursor / Windsurf config

{
  "mcpServers": {
    "swarmhawk": {
      "url": "https://swarmhawk.com/api/mcp",
      "headers": { "X-API-Key": "swh_your_key" }
    }
  }
}

MCP Tools

Python SDK

The SwarmHawk Python SDK gives security platforms a clean programmatic interface to pull findings, configure push integrations, and consume STIX 2.1 bundles — no raw HTTP required.

SDK Methods

Integration API

Configure push integrations so SwarmHawk automatically sends critical findings to your security platforms the moment they're detected (risk ≥ 70).

GET /integrations

List all configured integrations for the authenticated user. Secrets are masked.

POST /integrations/{service}

Save or update integration config. service is one of: splunk · sentinel · crowdstrike · gravityzone · cortex · jira · servicenow · webhook · stix

POST /integrations/{service}/test

Test connectivity without saving. Returns {"ok": true, "message": "..."}

DEL /integrations/{service}

Remove an integration config.

Supported services

STIX / TAXII 2.1

SwarmHawk exposes a TAXII 2.1-compliant endpoint. Connect any threat intelligence platform (OpenCTI, MISP, ThreatConnect, Anomali) to pull SwarmHawk findings as STIX 2.1 objects.

GET /taxii/collections/

TAXII discovery endpoint — returns collection metadata.

GET /taxii/collections/swarmhawk/objects/

Returns a STIX 2.1 bundle of your high-risk domains as domain-name, vulnerability, and relationship objects.

STIX object types returned

All object IDs are deterministic (UUID5) — the same domain always produces the same STIX ID across bundle generations, enabling proper deduplication in downstream TIPs.

Real-Time Alerts — SSE

Subscribe to a live stream of new high-risk findings as they're detected. Uses standard Server-Sent Events (no WebSocket library needed).

GET /stream/alerts

Adapter Scripts

Standalone Python scripts for platforms where you prefer a scheduled pull (cron / Lambda / Azure Function) over the always-on push connector. Each script fetches SwarmHawk alerts and pushes them into the target platform in one run.

Splunk TA Adapter

Emits sourcetype=swarmhawk:scan events with CIM-aligned fields: dest, vendor_product, category, severity.

Microsoft Sentinel Adapter

Data lands in SwarmHawk_CL custom table. KQL example: SwarmHawk_CL | where RiskScore_d >= 80 | sort by TimeGenerated desc

CrowdStrike Falcon Adapter

Pushes domains as IOCs (type=domain) in batches of 200. Action is prevent for confirmed malware/phishing, detect for CVE exposure.

Bitdefender GravityZone Adapter

Creates custom network rules via createCustomRule. Action is block for malware/phishing, report for CVE exposure.

Palo Alto Cortex XDR Adapter

Sends external alerts with MITRE ATT&CK technique tags (T1566, T1190, T1046, T1557…). Batches of 100 per API call.

Jira Adapter

Creates structured ADF issues with risk summary table, CVE findings, software stack, failed checks, remediation bullets, and NIS2 label. Only fires when risk ≥ 70 AND cvss ≥ min_cvss to avoid ticket spam.

ServiceNow Adapter

Response Objects

Check object

Risk score interpretation

Check Names

Try It Live

Full interactive API explorer — execute real requests against the SwarmHawk API directly from your browser. Paste your API key into the Authorize button to unlock authenticated endpoints.