Alerts API

The Alerts API retrieves alerts and events about exposures and security incidents across your organization's assets.

info

This API endpoint is available for enterprise accounts only.

Get Alerts

Retrieve alerts and events of exposures for your organization.

HTTP Request

GET https://fullhunt.io/api/v1/enterprise/alerts

Query Parameters

Parameter	Required	Type	Description
org	No	string	Filter alerts by organization ID
page	No	integer	Page number (default: 1)
from	No	string	Get alerts from date (format: DD/MM/YYYY)
to	No	string	Get alerts until date (format: DD/MM/YYYY)

Example Request

curl "https://fullhunt.io/api/v1/enterprise/alerts" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

Example Request with Filters

curl "https://fullhunt.io/api/v1/enterprise/alerts?org=3db40e1c-1d26-4309-b0c4-105fde3b3486&from=01/01/2024&to=31/12/2024" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

Example Response

[
  {
    "domain": "acme.com",
    "host": "api-payments-prod.acme.com",
    "id": 92731,
    "is_seen": false,
    "message": "A new subdomain was discovered in `acme.com`. \n\n* Subdomain: `api-payments-prod.acme.com`\n* Detection Method: DNS Enumeration\n* First Seen: 2024-02-05 14:23:59 UTC",
    "timestamp": 1707142800,
    "title": "New subdomain discovered in `acme.com`",
    "type": "new_subdomain_discovered"
  }
]

Response Fields

Field	Type	Description
domain	string	The affected domain
host	string	The specific host/subdomain affected
id	integer	Unique alert identifier
is_seen	boolean	Whether the alert has been acknowledged
message	string	Detailed alert message with context
timestamp	integer	Unix timestamp when alert was created
title	string	Alert title/summary
type	string	Type of alert (e.g., "new_subdomain_discovered")

Alert Types

New Subdomain Discovered

Triggered when new subdomains are discovered for your monitored domains.

{
  "type": "new_subdomain_discovered",
  "title": "New subdomain discovered in `example.com`",
  "message": "A new subdomain was discovered..."
}

New Vulnerability Found

Triggered when vulnerabilities are discovered on your assets.

{
  "type": "vulnerability_discovered",
  "title": "Critical vulnerability found on api.example.com",
  "message": "A critical vulnerability (CVE-2024-1234) was discovered..."
}

Certificate Expiration Warning

Triggered when SSL certificates are about to expire.

{
  "type": "certificate_expiring",
  "title": "SSL certificate expiring for api.example.com",
  "message": "SSL certificate will expire in 7 days..."
}

New Technology Detected

Triggered when new technologies are detected on your assets.

{
  "type": "technology_change",
  "title": "New technology detected on www.example.com",
  "message": "Apache/2.4.52 detected on www.example.com..."
}

Pagination

Use the page parameter to paginate through results:

# Get page 1 (default)
curl "https://fullhunt.io/api/v1/enterprise/alerts?page=1" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

# Get page 2
curl "https://fullhunt.io/api/v1/enterprise/alerts?page=2" \
  -H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"

Integration Example

import requests
from datetime import datetime, timedelta

def get_recent_alerts(api_key, days=7):
    """Get alerts from the last N days."""
    
    # Calculate date range
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days)
    
    # Format dates for API
    from_date = start_date.strftime("%d/%m/%Y")
    to_date = end_date.strftime("%d/%m/%Y")
    
    url = "https://fullhunt.io/api/v1/enterprise/alerts"
    headers = {"X-API-KEY": api_key}
    params = {
        "from": from_date,
        "to": to_date,
        "page": 1
    }
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 200:
        alerts = response.json()
        
        print(f"Found {len(alerts)} alerts in the last {days} days:")
        
        for alert in alerts:
            seen_status = "✓" if alert['is_seen'] else "✗"
            print(f"{seen_status} [{alert['type']}] {alert['title']}")
            print(f"   Host: {alert['host']}")
            print(f"   Time: {datetime.fromtimestamp(alert['timestamp'])}")
            print()
            
        return alerts
    else:
        print(f"Error: {response.status_code}")
        return None

# Usage
api_key = "your-api-key-here"
recent_alerts = get_recent_alerts(api_key, days=30)

Webhook Integration

For real-time alert notifications, consider setting up webhooks (contact enterprise support):

# Example webhook handler
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/fullhunt-alerts', methods=['POST'])
def handle_alert():
    alert_data = request.json
    
    # Process the alert
    alert_type = alert_data.get('type')
    domain = alert_data.get('domain')
    message = alert_data.get('message')
    
    # Send to your monitoring system
    send_to_slack(f"🚨 FullHunt Alert: {alert_type} for {domain}")
    
    return jsonify({"status": "received"})

def send_to_slack(message):
    # Your Slack integration logic here
    pass

Rate Limiting

• Rate limit: 60 requests per minute
• Large organizations may request higher limits
• Use pagination to handle large result sets efficiently