Whisper

# Whisper Security Threat Intelligence API

The Whisper Security API provides comprehensive threat intelligence, geolocation data,
and security operations capabilities for enterprise security teams and developers.

## Key Capabilities

- **Indicator Enrichment**: Get comprehensive intelligence on IP addresses and domains including
  geolocation, WHOIS, DNS, reputation scoring, and relationship mapping.
- **Geolocation Services**: Fast IP-to-location lookups with ISP, ASN, and network information.
- **Security Operations**: Asynchronous tools for bulk enrichment, infrastructure scanning,
  AI-powered threat investigation, and monitoring.

## API Design

- **RESTful**: Standard HTTP methods (GET, POST, PUT, DELETE) with JSON request/response bodies.
- **Synchronous Endpoints**: Fast responses (<500ms) for indicator enrichment and geolocation.
- **Asynchronous Jobs**: Long-running operations return a job ID for polling results.
- **Consistent Error Handling**: Standardized error responses with status codes, error codes, and messages.

## Authentication

All API endpoints require Bearer token authentication. Include your API key in the
`Authorization` header: `Authorization: Bearer <your-api-key>`

## Rate Limits

Rate limits are applied per-user and vary by endpoint category:

| Endpoint Category | Rate Limit | Description |
|-------------------|------------|-------------|
| Indicators (`/v1/indicators/*`) | 100 req/sec | Single indicator enrichment |
| Location (`/v1/location/*`) | 100 req/sec | Geolocation lookups |
| Jobs (`/v1/ops/jobs/*`) | 100 req/sec | Job status and listing |
| Bulk Operations (`/v1/ops/enrichment/bulk`) | 10 req/sec | Bulk indicator processing |
| Screenshots (`/v1/ops/screenshots/*`) | 10 req/sec | Screenshot capture and scheduling |
| Scans (`/v1/ops/scans/*`) | 10 req/sec | Infrastructure scanning |
| Monitoring (`/v1/ops/monitoring/*`) | 10 req/sec | Uptime monitoring |
| Tracking (`/v1/ops/tracking/*`) | 10 req/sec | Change tracking |
| AI Investigate (`/v1/ops/ai/investigate`) | 5 req/min | Deep threat investigation |
| AI Correlate (`/v1/ops/ai/correlate`) | 5 req/min | Global correlation |
| AI Attribute (`/v1/ops/ai/attribute`) | 5 req/min | Threat actor attribution |
| AI Pivot (`/v1/ops/ai/pivot`) | 5 req/min | Infrastructure pivoting |

When rate limits are exceeded, the API returns HTTP `429 Too Many Requests` with a
`Retry-After` header indicating when you can retry. The response body includes:
```json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for <category>. Please retry after N seconds.",
  "retryAfter": N
}
```

## Response Conventions

- All timestamps are in ISO 8601 format (UTC).
- Pagination uses `limit` and `offset` parameters.
- Field names use camelCase throughout the API.

## Official SDKs

- **Python**: [github.com/whisper-sec/sdk-python](https://github.com/whisper-sec/sdk-python)
- **TypeScript/JavaScript**: [github.com/whisper-sec/sdk-typescript](https://github.com/whisper-sec/sdk-typescript)
- **Java**: [github.com/whisper-sec/sdk-java](https://github.com/whisper-sec/sdk-java)
- **C#/.NET**: [github.com/whisper-sec/sdk-csharp](https://github.com/whisper-sec/sdk-csharp)

## Resources

- **Website**: [whisper.security](https://whisper.security)
- **Dashboard**: [dash.whisper.security](https://dash.whisper.security) - Manage API keys and view usage
- **Documentation**: [docs.whisper.security](https://docs.whisper.security) - Guides and tutorials


Whisper Security API

**Uptime and Availability Monitoring**

Configure monitoring checks for websites, APIs, and infrastructure endpoints.
Receive alerts when targets become unavailable or experience issues.

**Check Types:**
- HTTP/HTTPS endpoint monitoring
- Response time tracking
- SSL certificate expiration alerts
- Custom threshold configuration

**Rate Limit:** 10 req/sec


Monitoring

Get details of a specific monitoring check including uptime metrics.

Get Monitoring Check

Update an existing monitoring check configuration.

Update Monitoring Check

Delete a monitoring check and stop all monitoring for the target.

Delete Monitoring Check

<p>Get a list of all monitoring checks created by the authenticated user.</p>
<h4>Filtering:</h4>
<ul>
    <li><b>type:</b> Filter by check type (api, ssl, dns)</li>
    <li><b>status:</b> Filter by status (passing, failing, degraded, pending)</li>
</ul>


List Monitoring Checks

<p>Create a new monitoring check to track uptime and performance of a URL or endpoint.</p>
<h4>Check Types:</h4>
<ul>
    <li><b>api:</b> HTTP/HTTPS endpoint monitoring - checks status code, response time, content</li>
    <li><b>ssl:</b> SSL certificate monitoring - validates certificate and tracks expiry</li>
    <li><b>dns:</b> DNS record monitoring - validates DNS resolution and record values</li>
</ul>
<h4>Frequency Options:</h4>
<p>Check frequency in minutes: 1, 5, 10, 15, 30, 60, 1440 (daily)</p>
<h4>Locations:</h4>
<p>Checks can run from multiple global locations: us-east-1, us-west-1, eu-west-1, ap-southeast-1</p>


Create Monitoring Check

<p>Configure alert notifications for a monitored target. Set up notifications for downtime, SSL expiry, DNS changes, and more.</p>
<h4>Alert Types:</h4>
<ul>
    <li><b>downtime:</b> Alert when target becomes unreachable</li>
    <li><b>dns_change:</b> Alert when DNS records change</li>
    <li><b>whois_change:</b> Alert when WHOIS data changes</li>
    <li><b>ssl_expiring:</b> Alert when SSL certificate is expiring (within threshold days)</li>
    <li><b>content_change:</b> Alert when page content changes significantly</li>
    <li><b>technology_change:</b> Alert when detected technologies change</li>
</ul>
<h4>Notification Channels:</h4>
<ul>
    <li><b>email:</b> Send alerts via email</li>
    <li><b>slack:</b> Post to Slack webhook</li>
    <li><b>webhook:</b> POST to custom webhook URL</li>
    <li><b>pagerduty:</b> Create PagerDuty incident</li>
</ul>


Configure Monitoring Alert

Trigger an immediate execution of a monitoring check.

Trigger Manual Check

<p>Get the execution history for a monitoring check.</p>
<h4>Response includes for each result:</h4>
<ul>
    <li>Timestamp of execution</li>
    <li>Success/failure status</li>
    <li>Response time</li>
    <li>HTTP status code (for API checks)</li>
    <li>Error message (if failed)</li>
</ul>


Get Check Results

<p>Get the current monitoring status and metrics for a domain or IP address.</p>
<h4>Metrics Returned:</h4>
<ul>
    <li>Uptime percentage (last 30 days)</li>
    <li>Average response time</li>
    <li>SSL certificate expiration countdown</li>
    <li>DNS change events</li>
    <li>WHOIS change events</li>
</ul>


Get Monitoring Status

<p>Get aggregated dashboard statistics for all monitoring checks.</p>
<h4>Includes:</h4>
<ul>
    <li>Total, passing, failing, and degraded check counts</li>
    <li>Average uptime percentages (24h, 7d, 30d)</li>
    <li>Average response time</li>
    <li>Checks grouped by type and status</li>
</ul>


Get Monitoring Dashboard

**Indicator Change Detection**

Track changes to indicators over time. Monitor WHOIS records, DNS configurations,
SSL certificates, and other attributes for modifications.

**Features:**
- Automatic periodic checks
- Manual on-demand checks
- Change history with diff details
- Configurable tracking parameters

**Rate Limit:** 10 req/sec


Change Tracking

<p>Retrieve detected changes for a tracked indicator. Returns the current tracking configuration,
baseline snapshot, and list of all detected changes.</p>
<h4>Response Includes:</h4>
<ul>
    <li><b>tracking:</b> Current tracking configuration (enabled, frequency, fields, next check)</li>
    <li><b>baseline:</b> The stored baseline snapshot data</li>
    <li><b>changes:</b> Array of detected changes with timestamps, old/new values</li>
    <li><b>totalChanges:</b> Total number of changes detected</li>
</ul>


Get Detected Changes

<p>Start tracking changes for an IP or domain. When tracking is started, a baseline snapshot is captured.
Subsequent checks will compare against this baseline and record any detected changes.</p>
<h4>Trackable Fields for Domains:</h4>
<ul>
    <li><b>dns:</b> A, AAAA, MX, NS, TXT, CNAME records</li>
    <li><b>whois:</b> Registrant, registrar, dates, nameservers</li>
    <li><b>ssl:</b> Certificate issuer, expiry, SAN</li>
    <li><b>subdomains:</b> Discovered subdomains</li>
    <li><b>ips:</b> Resolved IP addresses</li>
</ul>
<h4>Trackable Fields for IPs:</h4>
<ul>
    <li><b>geolocation:</b> Country, city, coordinates</li>
    <li><b>asn:</b> ASN number, organization</li>
    <li><b>routing:</b> BGP routing status</li>
    <li><b>rpki:</b> RPKI validation status</li>
    <li><b>reverse_dns:</b> PTR records</li>
</ul>
<h4>Frequencies:</h4>
<ul>
    <li><b>hourly:</b> Check every hour</li>
    <li><b>daily:</b> Check once per day (default)</li>
    <li><b>weekly:</b> Check once per week</li>
</ul>


Start Change Tracking

<p>Stop tracking changes for an indicator. Optionally delete all change history.</p>


Stop Change Tracking

<p>Trigger an immediate check for changes on a tracked indicator. Creates a job to compare
current data against the stored baseline.</p>


Trigger Immediate Check

<p>Get a list of all indicators currently being tracked for changes by the authenticated user.</p>


List Tracked Indicators

**Website Screenshot Capture**

Capture screenshots of websites for visual analysis, brand monitoring,
and phishing detection. Supports one-time captures and scheduled recurring captures.

**Features:**
- Full page or viewport capture
- PNG/JPEG format support
- Scheduled recurring captures
- Screenshot history and change detection

**Rate Limit:** 10 req/sec


Screenshots

<p>Create a recurring job to capture website screenshots at regular intervals. Essential for monitoring website changes, detecting defacements, and tracking competitor updates.</p>
<h4>Schedule Options:</h4>
<ul>
    <li><b>Cron Expression:</b> Full cron syntax support (e.g., `0 0 * * * *` = hourly)</li>
    <li><b>Frequency Presets:</b> hourly, every_6_hours, every_12_hours, twice_daily, daily, weekly, monthly</li>
    <li><b>Timezone:</b> Specify timezone for accurate scheduling (default: UTC)</li>
</ul>
<h4>First Screenshot:</h4>
<p>The <b>first screenshot is captured immediately</b> when a schedule is created. Subsequent screenshots follow the configured schedule. This ensures you have baseline data right away.</p>
<h4>Limits:</h4>
<ul>
    <li><b>Max Schedules:</b> 3 per API key</li>
    <li><b>Max Screenshots:</b> 50 retained per schedule (oldest deleted automatically)</li>
    <li><b>Schedule Expiration:</b> Schedules auto-expire after 90 days of inactivity</li>
    <li><b>Screenshot Retention:</b> Individual screenshots expire after 14 days</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Setup Time:</b> ~2 seconds to create schedule</li>
    <li><b>First Screenshot:</b> Triggered immediately on schedule creation</li>
    <li><b>Screenshot Time:</b> 10-30 seconds per capture</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Automated defacement detection</li>
    <li>Compliance monitoring and archival</li>
    <li>Competitor website tracking</li>
    <li>Visual regression testing</li>
</ul>
<h4>Management:</h4>
<p>Use <code>GET /v1/ops/screenshots/schedules</code> to list schedules, <code>DELETE /v1/ops/screenshots/schedules/{id}</code> to delete.</p>


Schedule Recurring Screenshots (Asynchronous)

<p>Initiates an asynchronous job to capture a screenshot of a website. Supports various viewport sizes, full-page captures, and JavaScript rendering.</p>
<p><b>Performance Note:</b> A typical screenshot capture takes 10-30 seconds. Poll the `/v1/ops/jobs/{jobId}` endpoint to retrieve the URL of the final image.</p>
<p><b>Output:</b> The job result will contain a URL to download the screenshot image in the specified format (PNG, JPEG, or WebP).</p>


Capture a Website Screenshot (Asynchronous)

<p>Retrieve all scheduled screenshot configurations for your API key. Each API key can have a maximum of 3 active schedules.</p>
<h4>Response Includes:</h4>
<ul>
    <li><b>Schedule ID:</b> Unique identifier for the schedule</li>
    <li><b>URL:</b> Target website being captured</li>
    <li><b>Frequency:</b> How often screenshots are taken</li>
    <li><b>Next Capture:</b> When the next screenshot will be taken</li>
    <li><b>Capture Count:</b> Total screenshots taken by this schedule</li>
    <li><b>Status:</b> Whether the schedule is enabled or paused</li>
</ul>
<h4>Limits:</h4>
<ul>
    <li><b>Max Schedules:</b> 3 per API key</li>
    <li><b>Max Screenshots:</b> 50 retained per schedule (oldest deleted automatically)</li>
    <li><b>Schedule Expiration:</b> Schedules auto-expire after 90 days of inactivity</li>
</ul>


List Screenshot Schedules

<p>Retrieve details for a specific screenshot schedule including configuration and capture history.</p>


Get Screenshot Schedule Details

<p>Delete a scheduled screenshot configuration and optionally all its captured screenshots.</p>
<p><b>Warning:</b> This action cannot be undone. All associated screenshots will be permanently deleted.</p>


Delete Screenshot Schedule

<p>Retrieve all previously captured screenshots for a specific URL, ordered by capture time (newest first). Includes download URLs and metadata for each capture.</p>
<h4>Response Includes:</h4>
<ul>
    <li><b>Download URL:</b> Direct link to screenshot image</li>
    <li><b>Capture Time:</b> Timestamp when screenshot was taken</li>
    <li><b>Dimensions:</b> Image width and height</li>
    <li><b>Format:</b> Image format (PNG, JPEG, WebP)</li>
    <li><b>File Size:</b> Size in bytes</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Review website evolution over time</li>
    <li>Compare screenshots for change detection</li>
    <li>Download historical screenshots for reporting</li>
</ul>


Get Screenshot History

<p>Delete all captured screenshots for a schedule while keeping the schedule active.</p>
<p><b>Warning:</b> This action cannot be undone. All screenshots will be permanently deleted.</p>


Clear Screenshot History

**Infrastructure Discovery and Security Scanning**

Asynchronous scanning operations for discovering and analyzing infrastructure.
Returns a job ID for polling results.

**Scan Types:**
- SSL certificate analysis and chain validation
- Technology stack detection
- Subdomain enumeration
- Port scanning
- Infrastructure relationship mapping

**Rate Limit:** 10 req/sec


Infrastructure Scanning

<p>Creates a comprehensive map of infrastructure relationships starting from a domain or IP. Discovers connected assets through shared hosting, DNS, certificates, and network relationships.</p>
<h4>Mapping Depth Levels:</h4>
<ul>
    <li><b>Depth 1:</b> Direct relationships only (~30 seconds, 10-50 assets)</li>
    <li><b>Depth 2:</b> 2 hops out (~2-5 minutes, 50-500 assets)</li>
    <li><b>Depth 3:</b> 3 hops out (~10-30 minutes, 500-5000 assets)</li>
</ul>
<h4>Relationship Types Discovered:</h4>
<ul>
    <li>Domains on same IP</li>
    <li>Domains sharing nameservers</li>
    <li>Domains with same SSL certificate</li>
    <li>IPs in same ASN</li>
    <li>Domains with same registrant</li>
</ul>
<h4>Output Format:</h4>
<p>Results returned as graph data compatible with visualization libraries (nodes and edges).</p>
<h4>Use Cases:</h4>
<ul>
    <li>Threat actor infrastructure mapping</li>
    <li>Discovering related phishing domains</li>
    <li>Finding shadow IT and forgotten assets</li>
</ul>


Map Infrastructure Relationships (Asynchronous)

<p>Initiates a security scan of a domain's infrastructure. Performs reconnaissance and configuration analysis.</p>
<h4>Scan Types:</h4>
<ul>
    <li><b>comprehensive:</b> Full scan including all modules (subdomains, dns, ssl, technologies, whois)</li>
    <li><b>subdomains:</b> Subdomain enumeration and discovery</li>
    <li><b>ssl:</b> SSL/TLS certificate analysis (issuer, validity, expiration, protocol)</li>
    <li><b>dns:</b> DNS record analysis and configuration</li>
    <li><b>technologies:</b> Technology stack detection via headers and NoctisEyes scan</li>
    <li><b>whois:</b> Domain registration and ownership information</li>
    <li><b>vulnerability:</b> Dedicated vulnerability scan using NoctisEyes (detects security misconfigurations, exposed services, known CVEs)</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Quick scans:</b> 10-30 seconds (ssl, dns, whois)</li>
    <li><b>Medium scans:</b> 30-60 seconds (subdomains)</li>
    <li><b>Technologies scan:</b> 2-5 minutes (includes NoctisEyes vulnerability scan)</li>
    <li><b>Vulnerability scan:</b> 2-5 minutes (dedicated NoctisEyes security scan with severity breakdown)</li>
    <li><b>Comprehensive scan:</b> 3-5 minutes (all modules in parallel)</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Pre-engagement reconnaissance for penetration testing</li>
    <li>Attack surface assessment</li>
    <li>SSL certificate monitoring</li>
    <li>Infrastructure inventory</li>
    <li>Vulnerability assessment and security audits</li>
</ul>


Infrastructure Security Scan (Asynchronous)

Direct access to the Whisper graph database via Cypher and GraphQL queries.

**Use Cases:**
- Advanced threat hunting with custom graph queries
- Exploring relationships between indicators
- Building custom visualizations and reports

**Available Node Types:**
`DomainName`, `A_ADDRESS`, `AAAA_ADDRESS`, `ASN`, `TLD`, `ANNOUNCED_PREFIX_4`,
`ANNOUNCED_PREFIX_6`, `Organisation`, `Country`, `LIST`, `LISTCATEGORY`, `TLSCA`, `TLSCert`

**Available Relationships:**
`hasIP`, `hasIPv6`, `hasNameserver`, `hasMailHost`, `hasTLD`, `announces`,
`inASN`, `isListed`, `hasCA`, `isIssuer`, `isSubjectOf`


Graph Database

Execute a GraphQL query against the graph database.

GraphQL provides a type-safe, structured alternative to Cypher
for querying the graph data.

**Available Query Operations:**
- `domain(name: String!)` - Look up domain information
- `ipv4(address: String!)` - Look up IPv4 address information
- `ipv6(address: String!)` - Look up IPv6 address information
- `asn(number: Int!)` - Look up ASN information
- `searchDomains(pattern: String!, limit: Int)` - Search domains by pattern
- `domainsOnIP(address: String!)` - Find domains on an IP
- `domainsOnASN(asnNumber: Int!, limit: Int)` - Find domains on an ASN
- `checkIndicator(indicator: String!)` - Check if indicator is listed

**Example Query:**
```graphql
{
  domain(name: "google.com") {
    name
    ipAddresses {
      address
      country { code }
    }
    nameservers { name }
    asns { number }
  }
}
```

Use the `/v1/ops/graph/graphiql` endpoint for an interactive
query explorer with schema documentation.


Execute GraphQL Query

Execute a read-only Cypher query against the FalkorDB graph database.

**Security:** Only read operations (MATCH, RETURN) are allowed.
Write operations are blocked.

**Example Queries:**
```cypher
// Find all IPs for a domain
MATCH (d:DomainName {name: $domain})-[:hasIP]->(ip:A_ADDRESS)
RETURN ip.name AS ip

// Find domains on blocklists
MATCH (d:DomainName)-[:isListed]->(l:LIST)
RETURN d.name, l.name LIMIT 10

// Get ASN and announced prefixes
MATCH (asn:ASN {number: 15169})-[:announces]->(p:ANNOUNCED_PREFIX_4)
RETURN p.name AS prefix
```

**Performance Tips:**
- Always use LIMIT to restrict result size
- Use parameters for variable values
- Filter early in the query with WHERE clauses


Execute Cypher Query

Retrieve the graph database schema including available node labels,
relationship types, and their properties.

Use this to discover what data is available for querying before
writing Cypher or GraphQL queries.

**Response includes:**
- Node labels (e.g., DomainName, A_ADDRESS, ASN)
- Relationship types (e.g., hasIP, isListed, announces)
- Properties available on each node and relationship type
- Graph statistics (node and relationship counts)


Get Graph Schema

Check the health and connectivity of the graph database.

**No authentication required** - this is a public health endpoint.

Returns database status, connection info, and basic statistics.


Graph Database Health Check

Access the GraphiQL interactive query explorer.

GraphiQL provides:
- Interactive query editor with syntax highlighting
- Auto-complete for types and fields
- Schema documentation browser
- Query history

**No authentication required** - the UI itself is public,
but queries still require a valid API key.


GraphiQL Interactive Explorer

**IP and Domain Enrichment**

Comprehensive threat intelligence enrichment for IP addresses and domains.
Includes both synchronous single-indicator lookups and asynchronous bulk operations.

**Synchronous (single indicator):**
High-performance lookups typically completing in under 500ms.
- Single IP/domain enrichment with geolocation, WHOIS, DNS, reputation
- Historical data and relationship graphs
- AI-powered predictive risk scoring

**Asynchronous (bulk):**
Process up to 100 indicators per request. Returns a job ID for polling results.
- Bulk indicator enrichment
- WHOIS field-based search (registrant name, email, organization)
- Typosquatting and lookalike domain detection

**Data Sources:**
Geolocation, WHOIS registration, DNS records, reputation scoring, BGP routing,
RPKI validation, SSL certificates, and relationship graphs.

**Rate Limits:** Sync: 100 req/sec | Bulk: 10 req/sec


Enrichment

<p>Finds domains similar to the provided domain using various similarity detection techniques.
This endpoint is useful for brand protection, typosquatting detection, and threat hunting.</p>

<h4>Supported Techniques:</h4>
<p>Specify techniques in the <code>techniques</code> array. If not specified, defaults to <code>typosquatting</code>.</p>
<ul>
    <li><b>typosquatting</b> - Keyboard proximity errors and common typos (e.g., gooogle.com, gogle.com)</li>
    <li><b>homoglyph</b> - Visually similar Unicode characters (e.g., gооgle.com using Cyrillic 'о')</li>
    <li><b>tld_variation</b> - Different TLD variations (e.g., google.net, google.org)</li>
    <li><b>sounding</b> - Phonetically similar domains</li>
    <li><b>prefix</b> - Domains starting with the target</li>
    <li><b>suffix</b> - Domains ending with the target</li>
    <li><b>contains</b> - Domains containing the target as a substring</li>
    <li><b>levenshtein</b> - Edit distance similarity</li>
</ul>

<h4>Example Request:</h4>
<pre><code>{
  "domain": "google.com",
  "techniques": ["typosquatting", "homoglyph", "tld_variation"],
  "limit": 100
}</code></pre>

<h4>Response Format:</h4>
<p>Poll <code>/v1/ops/jobs/{jobId}</code> to get results. The result contains:</p>
<pre><code>{
  "domain": "google.com",
  "status": "completed",
  "similarDomains": [
    {"domain": "gooogle.com", "technique": "TYPO"},
    {"domain": "gооgle.com", "technique": "UTFVARS"}
  ],
  "totalCount": 200,
  "analysis": {
    "techniquesUsed": "TYPO,UTFVARS",
    "baseDomain": "google.com",
    "searchLimit": 100
  }
}</code></pre>

<h4>Performance:</h4>
<p>Typically completes in 5-15 seconds. Multiple techniques run in parallel.</p>

<h4>Note:</h4>
<p>The <code>check_registration</code>, <code>include_dns</code>, and <code>include_risk_score</code> options
are not currently supported by the backend service and will be ignored.</p>


Find Similar Domains (Asynchronous)

            <p>Initiates an asynchronous job to search domain registration (WHOIS) or IP geolocation records. This endpoint is extremely powerful for infrastructure discovery, threat hunting, and brand protection.</p>
            <p><b>Performance Note:</b> WHOIS searches are data-intensive and can take over 50 seconds to complete. Geolocation searches are faster (5-10 seconds). This endpoint is asynchronous by design. Poll the <code>/v1/ops/jobs/{jobId}</code> endpoint to retrieve results.</p>

            <h4>Search Types:</h4>
            <p>The endpoint automatically routes to the appropriate backend based on the fields provided:</p>
            <ul>
                <li><b>WHOIS Search:</b> Use registrant fields (registrantCompany, registrantEmail, etc.) or domain-related fields (tld, nameServer, etc.)</li>
                <li><b>Geolocation Search:</b> Use IP geolocation fields (city, country, asn, isp, etc.) to find IPs matching criteria</li>
            </ul>

            <h4>WHOIS Search Fields:</h4>
            <table>
                <tr><th>Field</th><th>Type</th><th>Description</th></tr>
                <tr><td><code>tld</code></td><td>exact</td><td>Top-level domain (e.g., "com", "org", "net")</td></tr>
                <tr><td><code>registrarName</code></td><td>exact</td><td>Domain registrar name</td></tr>
                <tr><td><code>registrarIanaId</code></td><td>exact</td><td>IANA registrar ID</td></tr>
                <tr><td><code>registrantName</code></td><td>text</td><td>Domain registrant name (partial match)</td></tr>
                <tr><td><code>registrantCompany</code></td><td>text</td><td>Registrant organization/company (partial match)</td></tr>
                <tr><td><code>registrantEmail</code></td><td>text</td><td>Registrant email address (supports *@domain.com wildcards)</td></tr>
                <tr><td><code>registrantPhone</code></td><td>text</td><td>Registrant phone number</td></tr>
                <tr><td><code>registrantCountry</code></td><td>text</td><td>2-letter country code (e.g., "US", "DE")</td></tr>
                <tr><td><code>registrantCity</code></td><td>text</td><td>Registrant city</td></tr>
                <tr><td><code>nameServer</code></td><td>text</td><td>Name server hostname</td></tr>
                <tr><td><code>domainStatus</code></td><td>text</td><td>Domain status flag (e.g., "clientTransferProhibited")</td></tr>
                <tr><td><code>createdDate</code></td><td>exact</td><td>Domain creation date (YYYY-MM-DD format)</td></tr>
                <tr><td><code>updatedDate</code></td><td>exact</td><td>Domain last update date (YYYY-MM-DD format)</td></tr>
                <tr><td><code>expiryDate</code></td><td>exact</td><td>Domain expiry date (YYYY-MM-DD format)</td></tr>
            </table>

            <h4>Geolocation Search Fields (query string syntax):</h4>
            <table>
                <tr><th>Field</th><th>Description</th><th>Example</th></tr>
                <tr><td><code>city</code></td><td>City name</td><td><code>city:London</code></td></tr>
                <tr><td><code>country</code></td><td>Country name</td><td><code>country:Germany</code></td></tr>
                <tr><td><code>asn</code></td><td>Autonomous System Number</td><td><code>asn:15169</code> (Google)</td></tr>
                <tr><td><code>isp</code></td><td>Internet Service Provider name</td><td><code>isp:Cloudflare</code></td></tr>
                <tr><td><code>organization</code></td><td>Organization name</td><td><code>organization:Amazon</code></td></tr>
                <tr><td><code>region</code></td><td>Region/State</td><td><code>region:California</code></td></tr>
                <tr><td><code>postal_code</code></td><td>Postal/ZIP code</td><td><code>postal_code:94043</code></td></tr>
                <tr><td><code>continent</code></td><td>Continent</td><td><code>continent:Europe</code></td></tr>
            </table>

            <h4>Example Requests:</h4>
            <p><b>WHOIS search (field-based):</b></p>
            <pre>{
  "registrantCompany": "Google",
  "registrantCountry": "US",
  "limit": 100,
  "page": 0
}</pre>
            <p><b>Geolocation search (find IPs by ASN):</b></p>
            <pre>{
  "query": "asn:15169",
  "limit": 100
}</pre>
            <p><b>Geolocation search (find IPs by city):</b></p>
            <pre>{
  "query": "city:Mountain View",
  "limit": 100
}</pre>
            <p><b>Date-based domain search:</b></p>
            <pre>{
  "createdDate": "2024-01-15",
  "tld": "com",
  "limit": 100
}</pre>

            <h4>Pagination:</h4>
            <ul>
                <li><code>limit</code>: Maximum 100 results per page (default: 100)</li>
                <li><code>page</code>: 0-indexed page number (default: 0)</li>
                <li><code>offset</code>: Alternative to page - number of results to skip</li>
            </ul>

            <h4>Use Cases:</h4>
            <ul>
                <li><b>Threat hunting:</b> Find domains/IPs registered by known malicious actors</li>
                <li><b>Infrastructure mapping:</b> Find all IPs in a specific ASN or organization</li>
                <li><b>Brand protection:</b> Monitor for domains similar to your brand</li>
                <li><b>Geolocation analysis:</b> Find IPs in specific geographic regions</li>
                <li><b>Investigation:</b> Track domains created on specific dates or IPs from specific ISPs</li>
            </ul>

            <h4>Security:</h4>
            <p>All search parameters are validated for:</p>
            <ul>
                <li>SQL injection prevention</li>
                <li>Command injection prevention</li>
                <li>Input length limits</li>
                <li>Format validation (dates, emails, country codes, etc.)</li>
            </ul>


Search WHOIS and Geolocation Records (Asynchronous)

<p>Process multiple indicators (IPs and/or domains) in a single request. This endpoint is optimized for batch processing and can handle up to 100 indicators per request.</p>

<h4>Performance</h4>
<p>Processing time depends on batch size and indicator types. IP enrichment is faster than domain enrichment.</p>
<ul>
    <li><b>IPs only:</b> 2-10 seconds for typical batches</li>
    <li><b>Domains only:</b> 10-30 seconds (WHOIS lookups are slower)</li>
    <li><b>Mixed:</b> 5-30 seconds depending on ratio</li>
</ul>

<h4>Rate Limits</h4>
<p>Limited to 10 requests per minute due to the resource-intensive nature of bulk operations.</p>

<h4>Response Structure</h4>
<p>When the job completes, the <code>result</code> field contains:</p>
<ul>
    <li><code>status</code>: "completed" or "failed"</li>
    <li><code>results</code>: Array of enriched indicator objects (see below)</li>
    <li><code>errors</code>: Array of failed enrichments with error details</li>
    <li><code>totalProcessed</code>: Number of indicators processed</li>
    <li><code>totalFailed</code>: Number of failed enrichments</li>
    <li><code>totalIndicators</code>: Total indicators in request</li>
    <li><code>successRate</code>: Percentage of successful enrichments (0-100)</li>
</ul>

<h4>Result Item Structure</h4>
<p>Each item in the <code>results</code> array includes:</p>
<ul>
    <li><code>indicator</code>: The original indicator value</li>
    <li><code>type</code>: "ip" or "domain"</li>
    <li><code>query</code>: Request metadata (type, value, timestamp, response_time_ms)</li>
    <li><code>summary</code>: Key information summary</li>
</ul>

<p><b>For IP indicators:</b></p>
<ul>
    <li><code>geolocation</code>: Country, city, coordinates, ISP, ASN</li>
    <li><code>network</code>: BGP routing data, prefix visibility, origins</li>
    <li><code>isp</code>: ISP name, organization, ASN</li>
    <li><code>reputation</code>: Risk score, blacklist scores</li>
    <li><code>relationships</code>: Related domains, shared infrastructure</li>
</ul>

<p><b>For domain indicators:</b></p>
<ul>
    <li><code>registration</code>: WHOIS data (registrar, dates, nameservers, status)</li>
    <li><code>dns</code>: DNS records (A, AAAA, MX, NS, TXT, CNAME)</li>
    <li><code>reputation</code>: Domain reputation, infrastructure scores</li>
    <li><code>relationships</code>: Related domains, incoming/outgoing links</li>
</ul>

<h4>Error Item Structure</h4>
<p>Each item in the <code>errors</code> array includes:</p>
<ul>
    <li><code>indicator</code>: The indicator that failed</li>
    <li><code>type</code>: "ip" or "domain"</li>
    <li><code>error</code>: true</li>
    <li><code>message</code>: Error description</li>
</ul>


Bulk Indicator Enrichment (Asynchronous)

<p>Retrieves comprehensive intelligence for a single IP address or domain. This is the primary, high-performance endpoint for synchronous enrichment.</p>
<p>It aggregates data from multiple sources, including geolocation, WHOIS, DNS, reputation scoring, and relationship mapping. Use the `include` parameter to request additional, deeper data sets that may have higher latency.</p>
<h4>Performance:</h4>
<ul>
    <li><b>Base Response:</b> Typically under 500ms.</li>
    <li><b>With `include=routing`:</b> First request may take up to 5 seconds; subsequent requests are cached for 5 minutes and respond in &lt;200ms.</li>
    <li><b>With `include=ip_intelligence`:</b> Adds 200-500ms of latency for each IP address resolved from the domain.</li>
</ul>


Enrich a Single Indicator (IP or Domain)

<p>Returns ML-based predictive risk assessment for an IP address or domain. Provides current risk scoring,
7-day and 30-day predictions, risk trajectory analysis, and contributing factors.</p>
<h4>Response Includes:</h4>
<ul>
    <li><b>Current Assessment:</b> Risk score (0-100), risk level, and confidence</li>
    <li><b>Predictions:</b> 7-day and 30-day risk forecasts with confidence intervals</li>
    <li><b>Trajectory:</b> Trend direction (improving/stable/worsening), velocity, stability</li>
    <li><b>Risk Factors:</b> Contributing factors with weights and descriptions</li>
    <li><b>Early Warnings:</b> Signals indicating potential future risk changes</li>
    <li><b>Similar Cases:</b> Historical indicators with similar profiles and their outcomes</li>
</ul>
<h4>Risk Levels:</h4>
<ul>
    <li><b>low:</b> Score 0-30 - Minimal observed risk</li>
    <li><b>medium:</b> Score 31-60 - Moderate risk, warrants monitoring</li>
    <li><b>high:</b> Score 61-80 - Elevated risk, investigation recommended</li>
    <li><b>critical:</b> Score 81-100 - Severe risk, immediate action advised</li>
</ul>
<h4>Performance:</h4>
<p>Pre-computed ML predictions. Response time typically under 500ms with 15-minute cache.</p>


Get AI Predictive Risk Score

<p>Retrieves time-series historical data for an IP address or domain. Track how infrastructure changes over time for threat intelligence and forensic analysis.</p>
<h4>History Types:</h4>
<ul>
    <li><b>whois:</b> Registration history - registrant changes, expiration updates, transfers</li>
    <li><b>routing:</b> BGP routing history - prefix announcements, ASN changes, route hijacks</li>
    <li><b>dns:</b> DNS resolution history - IP address changes, nameserver updates</li>
    <li><b>ssl:</b> Certificate history - cert replacements, CA changes, expiration events</li>
    <li><b>reputation:</b> Risk score history - blacklist appearances, reputation changes</li>
</ul>
<h4>Data Format:</h4>
<p>Timeline with dated snapshots showing what changed and when:</p>
<pre><code>{
  "history": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "field": "registrant_company",
      "old_value": "Evil Corp",
      "new_value": "Legitimate LLC"
    }
  ]
}</code></pre>
<h4>Use Cases:</h4>
<ul>
    <li>Tracking domain ownership changes</li>
    <li>Investigating IP reputation degradation</li>
    <li>Forensic timeline reconstruction</li>
    <li>Detecting infrastructure pivots by threat actors</li>
</ul>


Get Historical Data for Indicator

<p>Returns graph visualization data showing relationships between the indicator and related infrastructure. Perfect for interactive network diagrams and threat actor infrastructure mapping.</p>
<h4>Relationship Types Included:</h4>
<ul>
    <li><b>For Domains:</b>
        <ul>
            <li>Resolves to IPs</li>
            <li>Shares nameservers with</li>
            <li>Same SSL certificate as</li>
            <li>Same registrant as</li>
            <li>Links to/from other domains</li>
        </ul>
    </li>
    <li><b>For IPs:</b>
        <ul>
            <li>Hosts domains</li>
            <li>Same ASN as</li>
            <li>Same network block as</li>
            <li>Connected via routing</li>
        </ul>
    </li>
</ul>
<h4>Output Format:</h4>
<p>Compatible with react-force-graph, vis.js, cytoscape.js:</p>
<pre><code>{
  "nodes": [
    {"id": "example.com", "type": "domain", "label": "example.com"},
    {"id": "8.8.8.8", "type": "ip", "label": "8.8.8.8"}
  ],
  "links": [
    {"source": "example.com", "target": "8.8.8.8", "type": "resolves_to"}
  ]
}</code></pre>
<h4>Performance:</h4>
<ul>
    <li>Response Time: 500ms-2s depending on graph complexity</li>
    <li>Default: 100 nodes maximum (adjustable)</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Interactive threat actor infrastructure visualization</li>
    <li>Discovering related phishing campaigns</li>
    <li>Mapping shadow IT and sprawl</li>
    <li>Network topology visualization</li>
</ul>


Get Infrastructure Relationship Graph

Retrieves a list of discovered subdomains for a given root domain, based on passive DNS and other enumeration techniques.

Get Domain Subdomains

**AI-Powered Threat Intelligence**

Advanced machine learning and LLM-powered analysis for threat investigation,
attribution, and correlation. These operations are computationally intensive
and return a job ID for polling results.

**Capabilities:**
- Deep threat investigation with verdict and recommendations
- Similar historical case matching
- Infrastructure pivoting and relationship discovery
- Threat actor attribution and TTP mapping
- Global indicator correlation across customers
- Industry security benchmarks (synchronous)

**Performance:**
Most AI operations complete in 30 seconds to 5 minutes depending on complexity.

**Rate Limit:** 5 requests per minute for async AI operations.


AI Intelligence

<p>Uses ML to find historical threat cases similar to the current investigation. Helps analysts understand attack patterns and expected outcomes.</p>
<h4>Matching Criteria:</h4>
<ul>
    <li>Indicator overlap and relationships</li>
    <li>Behavioral patterns and TTPs</li>
    <li>Infrastructure characteristics</li>
    <li>Attack progression similarities</li>
</ul>
<h4>Response Includes:</h4>
<ul>
    <li>Similar cases with similarity scores</li>
    <li>Case outcomes and verdicts</li>
    <li>Common patterns across matches</li>
</ul>
<h4>Performance:</h4>
<p>ML similarity matching. Expected completion: 5-30 seconds.</p>


Find Similar Cases (Asynchronous)

<p>Performs intelligent infrastructure pivoting starting from an indicator. Uses ML to identify the most relevant relationships and suggest investigation paths.</p>
<h4>Pivot Strategies:</h4>
<ul>
    <li><b>infrastructure:</b> Shared hosting, nameservers, certificates</li>
    <li><b>registration:</b> Same registrant, registration patterns</li>
    <li><b>behavioral:</b> Similar traffic patterns, communication</li>
    <li><b>temporal:</b> Co-occurrence within time windows</li>
</ul>
<h4>Response Includes:</h4>
<ul>
    <li>Discovered related indicators with relevance scores</li>
    <li>Suggested investigation paths ranked by priority</li>
    <li>Relationship graph data</li>
</ul>
<h4>Performance:</h4>
<p>Graph traversal with ML ranking. Expected: 10-120 seconds based on depth.</p>


AI Infrastructure Pivot (Asynchronous)

<p>Initiates a comprehensive AI-powered threat investigation for an indicator. Uses large language models to analyze threat intelligence, generate insights, and provide actionable recommendations.</p>
<h4>Investigation Output:</h4>
<ul>
    <li><b>Verdict:</b> Threat assessment with confidence score</li>
    <li><b>Timeline:</b> Activity timeline reconstruction</li>
    <li><b>Analysis:</b> Detailed findings from multiple data sources</li>
    <li><b>Related Indicators:</b> Discovered related infrastructure</li>
    <li><b>Recommendations:</b> Suggested response actions</li>
</ul>
<h4>Performance:</h4>
<p>LLM-based analysis. Expected completion: 30-180 seconds depending on complexity.</p>


AI Threat Investigation (Asynchronous)

<p>Correlates your indicators against anonymized global threat data from all customers. Identifies shared campaigns, widespread threats, and prevalence across industries.</p>
<h4>Correlation Analysis:</h4>
<ul>
    <li><b>Prevalence:</b> How common are these indicators across our customer base</li>
    <li><b>Industry Breakdown:</b> Which industries are seeing these indicators</li>
    <li><b>Campaign Detection:</b> Are these part of a broader campaign</li>
    <li><b>First/Last Seen:</b> Global timeline of indicator activity</li>
    <li><b>Co-occurrence:</b> Indicators frequently seen together</li>
</ul>
<h4>Limitations:</h4>
<p>Maximum 100 indicators per request.</p>
<h4>Performance:</h4>
<p>Cross-customer correlation. Expected: 10-60 seconds.</p>


Global Indicator Correlation (Asynchronous)

<p>Analyzes indicators and context to identify potential threat actors and campaigns. Uses ML clustering and TTP matching against known threat actor profiles.</p>
<h4>Attribution Analysis:</h4>
<ul>
    <li><b>Actor Identification:</b> Potential threat actor matches with confidence</li>
    <li><b>Campaign Clustering:</b> Groups indicators into potential campaigns</li>
    <li><b>TTP Mapping:</b> MITRE ATT&CK technique mapping</li>
    <li><b>Historical Context:</b> Known actor activity patterns</li>
</ul>
<h4>Limitations:</h4>
<p>Maximum 500 indicators per request. Attribution is probabilistic and should be validated.</p>
<h4>Performance:</h4>
<p>Campaign clustering and analysis. Expected: 60-300 seconds.</p>


Threat Actor Attribution (Asynchronous)

<p>Returns anonymized, aggregated security metrics for your industry vertical. Compare your security posture against peers.</p>
<h4>Available Industries:</h4>
<ul>
    <li>financial_services, healthcare, technology, retail, manufacturing</li>
    <li>energy, telecommunications, government, education, media</li>
</ul>
<h4>Metrics Included:</h4>
<ul>
    <li><b>Risk Scores:</b> Average risk score, percentiles (25th, 50th, 75th, 90th)</li>
    <li><b>Response Metrics:</b> Mean time to detect (MTTD), mean time to respond (MTTR)</li>
    <li><b>Detection Metrics:</b> Detection rate, false positive rate</li>
    <li><b>Threat Profile:</b> Top threats, common attack vectors, targeted assets</li>
    <li><b>Trends:</b> 30-day risk trend direction and change percentage</li>
</ul>
<h4>Performance:</h4>
<p>Pre-aggregated data. Response time typically under 500ms with 1-hour cache.</p>


Get Industry Security Benchmark (Synchronous)

**Fast Geolocation and Network Lookups**

Ultra-fast IP geolocation with ISP, ASN, and network classification data.
Optimized for real-time fraud detection and access control use cases.

**Performance:**
Single IP lookups typically respond in <150ms with 6-hour caching.

**Rate Limit:** 100 req/sec


Location

<p>Retrieve geolocation data for up to 1000 IP addresses in a single request. Optimized for batch processing with parallel lookups.</p>
<h4>Request Format:</h4>
<p>Send a JSON object with an <code>ips</code> array:</p>
<pre><code>{"ips": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]}</code></pre>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> 2-5 seconds for small batches (1-10 IPs), 5-15 seconds for larger batches</li>
    <li><b>Processing:</b> Parallel lookups with concurrency of 10</li>
    <li><b>Limit:</b> Maximum 1000 IPs per request</li>
    <li><b>Rate Limit:</b> 10 requests per minute</li>
</ul>
<h4>Response Format:</h4>
<p>Returns an array of geolocation objects, one for each requested IP:</p>
<p><b>Successful lookup fields:</b></p>
<ul>
    <li><code>queriedIp</code>: The IP address that was looked up (for correlation)</li>
    <li><code>country</code>: Object with <code>isoCode</code> (e.g., "US"), <code>name</code> (e.g., "United States")</li>
    <li><code>city</code>: Object with <code>name</code> (e.g., "Mountain View")</li>
    <li><code>location</code>: Object with <code>latitude</code>, <code>longitude</code>, <code>timeZone</code></li>
    <li><code>isp</code>: Object with <code>name</code>, <code>organization</code>, <code>asn</code>, <code>asnOrganization</code></li>
    <li><code>coordinates</code>: Object with <code>latitude</code>, <code>longitude</code> (convenience field)</li>
    <li><code>traits</code>: Object with <code>userType</code> (e.g., "hosting", "residential")</li>
</ul>
<p><b>Failed lookup fields:</b></p>
<ul>
    <li><code>ip</code>: The IP address that failed</li>
    <li><code>error</code>: Always <code>true</code> for failed lookups</li>
    <li><code>message</code>: Error description (e.g., "Invalid IP address format", "Location data not available for private IP addresses", "Location data not available for reserved/bogon IP addresses")</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Batch enrichment of access logs</li>
    <li>Bulk fraud scoring</li>
    <li>Geographic distribution analysis</li>
    <li>Network infrastructure mapping</li>
</ul>


Bulk IP Geolocation Lookup

<p>Returns metadata and statistics about the geolocation database, including coverage, update frequency, and data quality metrics.</p>
<h4>Statistics Included:</h4>
<ul>
    <li><b>Coverage:</b> Total IP addresses, networks, and ASNs covered</li>
    <li><b>Geographic:</b> Number of countries, cities, and regions</li>
    <li><b>Freshness:</b> Last update timestamp and update frequency</li>
    <li><b>Data Sources:</b> Providers and data collection methods</li>
    <li><b>Accuracy:</b> Quality metrics and confidence scores</li>
</ul>
<h4>Performance:</h4>
<p><b>Note:</b> This endpoint aggregates data from the entire database and may take 5-10 seconds to respond. Consider caching results on your end for repeated access.</p>
<h4>Use Cases:</h4>
<ul>
    <li>Verifying database coverage for your use case</li>
    <li>Monitoring data freshness</li>
    <li>Understanding data quality and accuracy</li>
</ul>


Get Geolocation Database Statistics

<p>Search the geolocation database by specific fields to find all IP addresses matching your criteria. Powerful for threat hunting, infrastructure discovery, and pattern analysis.</p>
<h4>Searchable Fields:</h4>
<ul>
    <li><b>Geographic:</b> city, country, country_code, region, postal_code, continent, continent_code</li>
    <li><b>Network:</b> asn, as_number, organization, isp, isp_name</li>
    <li><b>Coordinates:</b> latitude, longitude</li>
</ul>
<h4>Query Examples:</h4>
<ul>
    <li><b>Find all IPs in a city:</b> field=city&value=London</li>
    <li><b>Find all IPs for an ASN:</b> field=asn&value=15169</li>
    <li><b>Find all IPs for an ISP:</b> field=isp_name&value=Google</li>
    <li><b>Find all IPs in country:</b> field=country_code&value=US</li>
</ul>
<h4>Result Limiting:</h4>
<ul>
    <li>Use the <code>limit</code> parameter to control the number of results (max 1000, default 100)</li>
    <li><b>Note:</b> Pagination is not currently supported. Use smaller <code>limit</code> values for faster responses.</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> 200-500ms depending on result size</li>
    <li><b>Rate Limit:</b> 5 searches per minute</li>
</ul>
<h4>Response Format:</h4>
<ul>
    <li><code>totalHits</code>: Total number of matching records in the database</li>
    <li><code>results</code>: Array of matching IP records (up to <code>limit</code>)</li>
    <li><code>timeTakenMs</code>: Query execution time in milliseconds</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Infrastructure mapping for threat actors</li>
    <li>Finding all IPs in a specific region for compliance</li>
    <li>Discovering VPN/proxy exit nodes</li>
    <li>Threat hunting by ISP or ASN</li>
</ul>


Search Geolocation Database by Field

<p>Returns geolocation and network information for an entire network range specified in CIDR notation. Useful for analyzing network blocks, ranges, and subnets.</p>
<h4>Supported Formats:</h4>
<ul>
    <li><b>IPv4 CIDR:</b> 192.168.1.0/24</li>
    <li><b>IPv6 CIDR:</b> 2001:db8::/32</li>
</ul>
<h4>Data Included:</h4>
<ul>
    <li><b>Network Details:</b> CIDR range, first/last IP, total addresses</li>
    <li><b>Geographic:</b> Country, city, region for the network block</li>
    <li><b>Network:</b> ASN, organization, ISP information</li>
    <li><b>Classification:</b> Network type and usage category</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Analyzing suspicious network ranges</li>
    <li>Bulk geolocation for network blocks</li>
    <li>Infrastructure mapping and reconnaissance</li>
</ul>


Get Network/CIDR Geolocation Data

<p>Returns comprehensive geolocation and network information for any IPv4 address. This is one of the fastest endpoints in the API, optimized for real-time fraud detection and access control.</p>
<p><b>Note:</b> IPv6 addresses are not currently supported. Please use IPv4 addresses only.</p>
<h4>Data Included:</h4>
<ul>
    <li><b>Geographic:</b> Country, city, region, postal code, coordinates, timezone</li>
    <li><b>Network:</b> ASN, ISP/organization name, network range</li>
    <li><b>Classification:</b> Connection type (residential, datacenter, VPN, proxy, hosting)</li>
    <li><b>Reputation:</b> Risk indicators and abuse scores</li>
</ul>
<h4>Performance:</h4>
<ul>
    <li><b>Response Time:</b> Typically &lt;150ms</li>
    <li><b>Cache:</b> Results cached for 6 hours by default</li>
</ul>
<h4>Use Cases:</h4>
<ul>
    <li>Real-time fraud detection in payment flows</li>
    <li>Geographic access control and compliance</li>
    <li>Bot and VPN detection</li>
    <li>Threat intelligence enrichment</li>
</ul>


Get IP Geolocation and ASN Data

**Asynchronous Job Management**

Manage and monitor long-running asynchronous operations. All async endpoints return
a job ID that can be used to poll for status and retrieve results.

**Job Lifecycle:**
- PENDING: Job is queued for processing
- PROCESSING: Job is currently being executed
- COMPLETED: Job finished successfully, results available
- FAILED: Job encountered an error

**Retention:**
Job results are retained for 24 hours after completion.

**Rate Limit:** 100 req/sec


Jobs

<p>Retrieves the current status and results of an asynchronous job. Poll this endpoint to check job progress.</p>
<h4>Polling Recommendations:</h4>
<ul>
    <li>For fast jobs (e.g., similar domains), poll every 1-2 seconds.</li>
    <li>For slow jobs (e.g., WHOIS search, screenshots), poll every 5-10 seconds.</li>
    <li>Implement an exponential backoff strategy for very long-running jobs.</li>
    <li>Stop polling when the status is `COMPLETED`, `FAILED`, or `CANCELLED`.</li>
</ul>
<h4>Job Statuses:</h4>
<ul>
    <li><b>PENDING:</b> Job is queued and waiting to start.</li>
    <li><b>PROCESSING:</b> Job is actively being processed.</li>
    <li><b>COMPLETED:</b> Job finished successfully, results are available.</li>
    <li><b>FAILED:</b> Job failed with an error.</li>
    <li><b>CANCELLED:</b> Job was cancelled by user or system.</li>
</ul>
<h4>Result Schemas by Job Type:</h4>
<ul>
    <li><b>ai-investigate:</b> InvestigateResult - verdict, timeline, analysis, recommendations</li>
    <li><b>ai-pivot:</b> PivotResult - related indicators, investigation paths, relationship graph</li>
    <li><b>ai-attribute:</b> AttributeResult - actor identification, campaign clustering, TTP mapping</li>
    <li><b>ai-correlate:</b> CorrelateResult - prevalence, industry breakdown, co-occurrence</li>
    <li><b>ai-similar-cases:</b> SimilarCasesResult - similar cases with similarity scores</li>
    <li><b>screenshot:</b> ScreenshotResult - screenshot URL, ID, capture time, metadata</li>
</ul>


Get Asynchronous Job Status and Results

<p>Retrieves a list of recent jobs for the authenticated user, optionally filtered by status.</p>
<h4>Query Parameters:</h4>
<ul>
    <li><b>status:</b> Filter by job status (PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED)</li>
    <li><b>limit:</b> Maximum number of jobs to return (default: 50, max: 100)</li>
    <li><b>offset:</b> Number of jobs to skip for pagination (default: 0)</li>
</ul>
<h4>Response Format:</h4>
<p>Returns a JSON object with a "jobs" array containing job summaries.</p>


List Recent Jobs

Default

Whisper API Reference Documentation

API Key

Whisper API Platform

Whisper API Gateway

Production API Server

Staging API Server (for testing)

Local Development Server

query

Name of the operation to execute (for documents with multiple operations)

operationName

Variables to pass to the query as key-value pairs

variables

Authorization

status

error

A human-readable error message providing more detail

message

Additional details about the error, including field-specific validation errors

details

timestamp

A unique trace ID for this request, useful for debugging

trace_id

path

The Cypher query to execute. Must be a read-only query (MATCH/RETURN).

Use `$paramName` syntax to reference parameters from the `parameters` map.


Query parameters as key-value pairs. Use `$key` in the query to reference these.

Supported value types: String, Number, Boolean, List, Map.


parameters

Maximum number of results to return. Overrides any LIMIT clause in the query.

limit

Query results as a list of records. Each record is a map of column name to value.

results

executionTimeMs

rowCount

columns

Whether the result was truncated due to limit

truncated

Available node labels in the graph.

Common node types:
- `DomainName`: Domain names (e.g., google.com)
- `A_ADDRESS`: IPv4 addresses
- `AAAA_ADDRESS`: IPv6 addresses
- `ASN`: Autonomous System Numbers
- `ANNOUNCED_PREFIX_4`: IPv4 prefixes announced via BGP
- `ANNOUNCED_PREFIX_6`: IPv6 prefixes announced via BGP
- `Organisation`: Organisations owning ASNs
- `Country`: Country information
- `LIST`: Blocklist/whitelist entries
- `LISTCATEGORY`: Categories of lists
- `TLD`: Top-level domains
- `TLSCA`: TLS Certificate Authorities
- `TLSCert`: TLS Certificates


nodeLabels

Available relationship types in the graph.

Common relationships:
- `hasIP`: Domain → A_ADDRESS (DNS A record)
- `hasIPv6`: Domain → AAAA_ADDRESS (DNS AAAA record)
- `hasNameserver`: Domain → DomainName (NS record)
- `hasMailHost`: Domain → DomainName (MX record)
- `hasTLD`: Domain → TLD
- `announces`: ASN → ANNOUNCED_PREFIX
- `inASN`: IP_PREFIX → ASN
- `isListed`: IP/Domain → LIST (blocklist membership)
- `hasCA`: TLSCert → TLSCA
- `isIssuer`: TLSCA → TLSCert
- `isSubjectOf`: DomainName → TLSCert


Sections

Ask an AI

Code with AI