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"
}

move

Monitor the progress and results of previously submitted scan requests using the scan ID returned from the on-demand scan endpoint.

HTTP Request

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

Request Body Parameters

Parameter	Required	Type	Description
scan_id	Yes	string	The unique scan identifier returned from the on-demand scan request
query_tags	No	object	Key-value pairs for client-specific tracking

Example Request

curl -X POST "https://fullhunt.io/api/v1/oem/on-demand-scan/scan-status" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "query_tags": {
      "client_name": "ACMECorp",
      "tracking_id": "track_123"
    }
  }'

Example Response

{
  "response": {
    "status": "success",
    "scan_info": {
      "scan_id": "550e8400-e29b-41d4-a716-446655440000",
      "target": "acme.com",
      "status": "scan_completed",
      "created_at": 1683721587,
      "completed_at": 1683728792
    },
    "timestamp": 1683729000
  }
}

Scan Status Values

Status	Description
`queued`	Scan request has been queued for processing
`in_progress`	Scan is currently being processed
`scan_completed`	Scan has finished successfully
`failed`	Scan encountered an error and could not complete

Scan Status Response Fields

Field	Type	Description
`response`	object	Main response object
`response.status`	string	Status of the request ("success")
`response.scan_info`	object	Detailed scan information
`response.scan_info.scan_id`	string	Unique identifier for the scan
`response.scan_info.target`	string	The target that was scanned
`response.scan_info.status`	string	Current status of the scan
`response.scan_info.created_at`	integer	Unix timestamp when scan was created
`response.scan_info.completed_at`	integer	Unix timestamp when scan completed (null if not completed)
`response.timestamp`	integer	Unix timestamp of the status check

Status Check Rate Limiting

10 requests per minute per API key
Status checks do not consume scan credits
Recommended polling interval: 30-60 seconds for active scans

Error Responses

Status Code	Description
400	Bad Request - missing scan_id parameter
404	Not Found - scan ID does not exist
401	Unauthorized - invalid API key
403	Forbidden - OEM access not enabled
429	Rate limit exceeded
500	Internal server error

Example Error Response

{
  "error": "Scan ID not found"
}

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

Trigger On-Demand Scan​

Supported Target Types​

Domain Names​

IP Ranges​

Single IP Addresses​

Response Fields​

Scan Processing​

Query Tags for Tracking​

Rate Limiting​

Validation Rules​

Domain Validation​

IP Range Validation​

Error Handling​

move​

Scan Status Values​

Scan Status Response Fields​

Status Check Rate Limiting​

Error Responses​

Use Cases​

Client Asset Discovery​

Security Assessment​

Compliance Monitoring​