Tutorial: Using HunterX as an API Server

Starting the Server

hunterx api --port 8443 --host 0.0.0.0

Health Check

curl http://localhost:8443/health

Response:

{"status": "healthy", "version": "6.0.0"}

Submit a Scan

curl -X POST http://localhost:8443/scan \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://example.com",
    "profile": "bounty",
    "format": "json"
  }'

Response:

{
  "scan_id": "abc123",
  "status": "pending",
  "created_at": "2026-07-22T12:00:00Z"
}

Poll Results

curl http://localhost:8443/scan/abc123

Completed response:

{
  "scan_id": "abc123",
  "status": "completed",
  "findings": [...],
  "summary": {
    "total": 5,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 2
  },
  "duration_seconds": 45
}

Python SDK

import requests

api = "http://localhost:8443"

# Submit
resp = requests.post(f"{api}/scan", json={
    "url": "http://example.com",
    "profile": "bounty"
})
scan_id = resp.json()["scan_id"]

# Poll
while True:
    result = requests.get(f"{api}/scan/{scan_id}").json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(2)

print(result)