Home/HunterX/API

HunterX API Reference

Complete reference for HunterX REST API including all endpoints, parameters, response formats, and usage examples.

API Overview

HunterX provides a comprehensive RESTful API for programmatic access to all scanner functionality.

Base URL

All API endpoints are accessible at: http://localhost:8443/api

Authentication

API Key authentication via X-API-Key header or api_key query parameter.

Header: X-API-Key: your-api-key-here

Query: ?api_key=your-api-key-here

Core Endpoints

Endpoint	Method	Description
/scan	POST	Start an asynchronous scan job
/scan/{id}	GET	Poll scan status and results
/scan/{id}	DELETE	Cancel a running scan
/scans	GET	List all scan jobs (with filtering and pagination)
/ai/providers	GET	List configured AI providers
/ai/chat	POST	Send a chat completion request
/agents	GET	List registered agents
/goals	POST	Create a new reasoning goal
/skills	GET	List all registered security skills
/skills/search	GET	Search skills by name, category, or MITRE technique
/payload/mutate	POST	Mutate a payload using specified techniques
/health	GET	System health check
/version	GET	Get platform version

Scan Endpoint Details

POST /scan

Start an asynchronous scan job with the specified parameters.


  "url": "http://target.com",
  "profile": "bounty",
  "preset": "full",
  "stealth": "low",
  "threads": 5,
  "timeout": 30,
  "retries": 3,
  "maxDepth": 3,
  "aiEnabled": false,
  "aiModel": "gpt-4",
  "aiProvider": "openai",
  "authMode": "none",
  "outputDir": "./reports",
  "reportFormats": ["json", "html"],
  "callbackUrl": "https://example.com/webhook"

GET /scan/{id}

Retrieve the status and results of a specific scan job.


  "id": "scan_1234567890abcdef",
  "status": "completed",
  "progress": 100,
  "startTime": "2026-07-15T10:30:00Z",
  "endTime": "2026-07-15T10:45:00Z",
  "target": "http://target.com",
  "findings": [
    {
      "id": "finding_1",
      "name": "SQL Injection",
      "description": "SQL injection vulnerability in login form",
      "severity": "high",
      "confidence": 0.95,
      "evidence": "...",
      "remediation": "Use parameterized queries..."
    }
  ],
  "statistics": {
    "totalRequests": 1245,
    "vulnerabilitiesFound": 5,
    "falsePositives": 0
  }

Usage Examples

Basic Scan Request

Start a simple scan using curl:

curl -X POST http://localhost:8443/api/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "url": "http://example.com",
    "profile": "bounty",
    "outputDir": "/tmp/reports"
  }'

Scan with AI Assistance

Start a scan with AI-powered analysis:

curl -X POST http://localhost:8443/api/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "url": "http://example.com",
    "profile": "gov",
    "preset": "full",
    "aiEnabled": true,
    "aiModel": "gpt-4",
    "aiProvider": "openai",
    "outputDir": "/tmp/reports"
  }'

Check Scan Status

Poll for scan completion:

# Start scan and get ID
SCAN_ID=$(curl -s -X POST http://localhost:8443/api/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"url": "http://example.com", "profile": "bounty"}' | jq -r '.id')

# Poll for results
while true; do
  STATUS=$(curl -s -H "X-API-Key: your-api-key-here" \
    http://localhost:8443/api/scan/$SCAN_ID | jq -r '.status')
  
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  
  echo "Scan status: $STATUS - waiting..."
  sleep 5
done

# Get final results
curl -s -H "X-API-Key: your-api-key-here" \
  http://localhost:8443/api/scan/$SCAN_ID

Webhook Notifications

Configure webhooks to receive notifications when scans complete:

curl -X POST http://localhost:8443/api/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "url": "http://example.com",
    "profile": "bounty",
    "callbackUrl": "https://your-domain.com/webhook/hunterx-complete",
    "callbackEvents": ["scan.completed", "scan.failed"]
  }'

Back to HunterX Hub