On-Demand Scan API

Trigger on-demand scans for domains and IP ranges through the OEM API. This endpoint allows OEM partners to initiate comprehensive security scans for their clients' assets.

warning

OEM API requires special partner access. Contact FullHunt sales to enable OEM capabilities on your account.

Trigger On-Demand Scan

Submit a request to scan a specific target (domain or IP range) with priority processing for OEM partners.

HTTP Request

POST https://fullhunt.io/api/v1/oem/on-demand-scan

Request Body Parameters

Parameter	Required	Type	Description
type	Yes	string	Type of scan to perform. Supports "domain" and "ip_range"
target	Yes	string	The target to scan (domain name or IP range in CIDR notation)
query_tags	No	object	Key-value pairs for client-specific tracking

Example Request - Domain Scan

curl -X POST "https://fullhunt.io/api/v1/oem/on-demand-scan" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "domain",
    "target": "acme.com",
    "query_tags": {
      "client_name": "ACMECorp",
      "workspace": "production",
      "scan_priority": "high"
    }
  }'

Example Request - IP Range Scan

curl -X POST "https://fullhunt.io/api/v1/oem/on-demand-scan" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ip_range",
    "target": "8.8.8.0/24",
    "query_tags": {
      "client_name": "ACMECorp",
      "workspace": "production"
    }
  }'

Example Response

{
  "response": {
    "status": "success",
    "message": "On-demand scan request for 'acme.com' has been successfully queued for processing",
    "target": "acme.com",
    "type": "domain",
    "scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1683721587
  }
}

Supported Target Types

Domain Names

Scan entire domains for comprehensive attack surface discovery.

{
  "type": "domain",
  "target": "example.com"
}

IP Ranges

Scan IP ranges in CIDR notation for infrastructure discovery.

{
  "type": "ip_range",
  "target": "10.0.0.0/24"
}

Single IP Addresses

Single IP addresses are automatically converted to /32 CIDR ranges.

{
  "type": "ip_range",
  "target": "8.8.8.8"
}

Response Fields

Field	Type	Description
response	object	Main response object
response.status	string	Status of the scan request ("success")
response.message	string	Human-readable status message
response.target	string	The target that was queued for scanning
response.type	string	Type of scan (domain/ip_range)
response.scan_id	string	Unique identifier for tracking the scan
response.timestamp	integer	Unix timestamp when the scan was queued

Scan Processing

• Priority Processing: OEM scans receive priority 2 (higher than standard scans)
• Queue Integration: Scans are sent to the enterprise SQS queue for processing
• Audit Logging: All scan requests are logged in OEM audit logs
• Result Integration: Scan results are integrated into the FullHunt database

Query Tags for Tracking

Use the query_tags parameter to track scans by client or context:

{
  "query_tags": {
    "client_id": "client_123",
    "client_name": "ACME Corporation", 
    "workspace": "production",
    "scan_type": "security_assessment",
    "user_id": "user456",
    "project_id": "proj_789"
  }
}

Rate Limiting

• 5 requests per minute per API key
• Higher limits available for high-volume partners
• Contact FullHunt sales for custom rate limits

Validation Rules

Domain Validation

• Must be a valid domain name format
• Supports all TLDs and subdomains
• International domain names (IDN) supported

IP Range Validation

• Must be valid CIDR notation (e.g., 8.8.8.0/24)

Error Handling

Status Code	Description
200	Success - scan queued
400	Bad Request - invalid parameters
401	Unauthorized - invalid API key
403	Forbidden - OEM access not enabled or credits exhausted
422	Unprocessable Entity - invalid target format
429	Rate limit exceeded
500	Internal server error

Example Error Response

{
  "error": "'invalid-domain' is not a valid domain"
}

Use Cases

Client Asset Discovery

• Scan client domains for comprehensive asset inventory
• Discover all subdomains and services
• Monitor infrastructure changes

Security Assessment

• Perform on-demand security scans for clients
• Trigger scans after infrastructure changes
• Validate security improvements

Compliance Monitoring

• Regular scans to ensure compliance standards
• Document security posture changes
• Generate audit trails for compliance reports