SDKs & Libraries | Whisper API Docs

The SDK provides a typed, modern interface for the Whisper API, which offers comprehensive data and monitoring for domains, IPs, and web infrastructure. Key features include domain and IP intelligence, subdomain discovery, and real-time streaming.

‍

Prerequisites

‍

Before you start, make sure you have the following:

Node.js 14.0 or higher.
An API Bearer token from Whisper Security.
TypeScript 4.0 or higher (recommended for the best experience).

Installation

‍

Install the SDK into your project using your preferred package manager.

‍

npm install whisper-api-sdk
# or
yarn add whisper-api-sdk

‍

Initialization & Authentication

‍

To get started, import and initialize the Configuration object with your API token. Then, you can create instances of the API clients you need.

‍

import { Configuration, DomainManagementApi, IntelligenceServicesApi } from 'whisper-api-sdk';

// 1. Configure authentication with your Bearer token
const config = new Configuration({
    accessToken: 'your-bearer-token-here',
    basePath: 'https://api.whisper.security' // This is the default and can be omitted
});

// 2. Initialize the API clients you need
const domainApi = new DomainManagementApi(config);
const intelligenceApi = new IntelligenceServicesApi(config);

‍

Core API Usage

‍

The SDK makes it simple to fetch detailed intelligence data.

‍

IP Intelligence

‍

Analyze an IP address to get its geolocation, network topology, and risk assessment.

‍

const ipData = await intelligenceApi.getIpIntelligence('8.8.8.8');

// The response is fully typed and includes:
// - ipData.summary: Organization, location, network, and risk score
// - ipData.geolocation: City-level location data with confidence scores
// - ipData.network: ASN and BGP prefix information

‍

Domain Intelligence

‍

Get a complete profile for any domain, including WHOIS, DNS, and more.

‍

const domainData = await intelligenceApi.getDomainIntelligence('example.com');

// The response contains:
// - domainData.summary: Registrar, key dates, and status
// - domainData.registration: The full WHOIS record
// - domainData.dns: All DNS records (A, AAAA, MX, etc.)

‍

Subdomain Discovery

‍

Find subdomains for a given base domain with flexible filtering.

‍

// Find all subdomains up to a limit of 100
const subdomains = await domainApi.findSubdomains(
    'example.com',
    100,  // limit
    'ALL' // level: ALL, IMMEDIATE, or MAX_DEPTH
);

console.log(subdomains.data);

‍

Advanced Features

‍

Streaming with Server-Sent Events (SSE)

‍

For real-time use cases, you can stream data instead of waiting for a complete response. This is perfect for populating live dashboards. You can use a library like eventsource in Node.js to handle the stream.

‍

import EventSource from 'eventsource';

const eventSource = new EventSource(
    'https://api.whisper.security/intelligence/v1/domain/example.com',
    {
        headers: {
            'Authorization': 'Bearer your-token-here',
            'Accept': 'text/event-stream'
        }
    }
);

eventSource.addEventListener('whois', (event) => {
    console.log('WHOIS data received:', JSON.parse(event.data));
});

eventSource.addEventListener('dns', (event) => {
    console.log('DNS records received:', JSON.parse(event.data));
});

eventSource.addEventListener('complete', (event) => {
    console.log('Stream complete.');
    eventSource.close();
});

‍

Error Handling

‍

The SDK uses Axios under the hood, so you can catch errors and inspect the response to handle different scenarios like authentication failures or rate limiting.

‍

try {
    const data = await intelligenceApi.getIpIntelligence('8.8.8.8');
} catch (error) {
    if (error.response) {
        // The server responded with a status code outside the 2xx range
        console.error('API Error:', error.response.status, error.response.data);
        if (error.response.status === 429) {
            console.error('Rate limit exceeded.');
        }
    } else if (error.request) {
        // The request was made but no response was received
        console.error('Network error:', error.message);
    }
}

‍

Best Practices

Token Security: Never hardcode tokens. Use environment variables (process.env.WHISPER_API_TOKEN) or a secret management service.
Rate Limiting: If you receive a 429 error, wait before retrying. Implement an exponential backoff strategy for robust applications.
Caching: Cache API responses when appropriate to improve performance and reduce API calls. A time-to-live (TTL) of 5 minutes is a good starting point.
Concurrency: When processing many items, limit the number of concurrent requests to avoid overwhelming the API and your own resources. Use a library like p-limit to manage batch processing.

‍

Whisper NodeJS SDK