API Documentation - isMalicious Threat Intelligence API

Welcome

Introduction to the isMalicious API

Welcome to the isMalicious API documentation. This API provides programmatic access to our comprehensive threat intelligence database, enabling you to check domains, IPs, emails, and URLs for malicious activity.

Base URL: https://ismalicious.com/api

Key Features:

•Real-time threat intelligence checks

•Email risk assessment - Analyze email addresses for breaches, reputation, and suspicious patterns

•Reputation scoring from 50+ sources

•Geolocation and WHOIS data

•Vulnerability scanning

•Downloadable blocklists

Getting Started:

1.Create an account at ismalicious.com/auth/register

2.Generate API keys from your dashboard

3.Make your first API call

Need Help?

•Support Page

•API Playground

Authentication

How to authenticate API requests

All API requests (except /blocklist/stats) require authentication using an API key.

Getting Your API Keys:

1.Log in to your account

2.Go to Account Settings

3.Generate a new API key pair (key + secret)

Authentication Header:

X-API-KEY: <base64_encoded_credentials>

Creating the Header Value:

Base64 encode your apiKey:apiSecret:

// JavaScript
const credentials = btoa(`${apiKey}:${apiSecret}`);

# Python
import base64
credentials = base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()

Security Best Practices:

•Never expose your API keys in client-side code

•Rotate keys regularly

•Use environment variables to store credentials

•Restrict keys to specific IPs if possible (Enterprise)

Check Endpoints

Threat intelligence check endpoints

GET

/api/check

Full Threat Analysis

Comprehensive threat intelligence check for IPs and domains. Returns reputation, risk score, geolocation, WHOIS, certificates, and vulnerability data.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	IP address or domain to check
`enrichment`	`string`	No	Level of data enrichment: basic, standard, or full (default: `standard`)
`trackReports`	`boolean`	No	Save this check to your reports history (default: `false`)

Example Request

curl -X GET "https://ismalicious.com/api/check?query=8.8.8.8&enrichment=standard" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "malicious": false,
  "reputation": {
    "malicious": 0,
    "suspicious": 0,
    "harmless": 85,
    "undetected": 15
  },
  "riskScore": {
    "score": 5,
    "level": "safe",
    "factors": []
  },
  "confidence": {
    "score": 95,
    "level": "high"
  },
  "classification": {
    "primary": "safe",
    "secondary": []
  },
  "geo": {
    "country": "United States",
    "countryCode": "US",
    "city": "Mountain View",
    "isp": "Google LLC"
  },
  "apiVersion": "v2",
  "enrichmentLevel": "standard"
}

GET

/api/check/reputation

Check Reputation

Get reputation data from aggregated threat intelligence sources including VirusTotal integration.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	IP address or domain

Example Request

curl -X GET "https://ismalicious.com/api/check/reputation?query=example.com" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "reputation": {
    "malicious": 0,
    "suspicious": 2,
    "harmless": 80,
    "undetected": 18
  }
}

GET

/api/check/location

Check Geolocation

Get geographic location data including country, city, region, ISP, and coordinates.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	IP address or domain

Example Request

curl -X GET "https://ismalicious.com/api/check/location?query=1.1.1.1" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "geo": {
    "country": "Australia",
    "countryCode": "AU",
    "city": "Sydney",
    "region": "New South Wales",
    "lat": -33.8688,
    "lon": 151.2093,
    "isp": "Cloudflare Inc"
  }
}

GET

/api/check/whois

Check WHOIS

Get WHOIS registration data including registrant, registrar, and dates.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	IP address or domain

Example Request

curl -X GET "https://ismalicious.com/api/check/whois?query=example.com" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "whois": {
    "registrar": "GoDaddy.com, LLC",
    "registrant": "REDACTED FOR PRIVACY",
    "createdDate": "1997-09-15T04:00:00.000Z",
    "updatedDate": "2023-08-14T07:00:00.000Z",
    "expiresDate": "2028-09-14T04:00:00.000Z",
    "nameServers": [
      "ns1.example.com",
      "ns2.example.com"
    ]
  }
}

GET

/api/check/certificates

Check Certificates

Get SSL/TLS certificate information including issuer, validity, and chain.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	Domain or IP address

Example Request

curl -X GET "https://ismalicious.com/api/check/certificates?query=google.com" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "certificates": {
    "issuer": "Let's Encrypt Authority X3",
    "subject": "example.com",
    "validFrom": "2024-01-01T00:00:00.000Z",
    "validTo": "2024-03-31T23:59:59.000Z",
    "serialNumber": "03:A1:B2:C3:D4:E5:F6",
    "fingerprint": "SHA256:ABC123..."
  }
}

GET

/api/check/vulnerabilities

Check Vulnerabilities

Get known vulnerabilities associated with an IP address from CVE databases.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	IP address

Example Request

curl -X GET "https://ismalicious.com/api/check/vulnerabilities?query=192.168.1.1" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "vulnerabilities": {
    "total": 3,
    "critical": 1,
    "high": 1,
    "medium": 1,
    "low": 0,
    "cves": [
      {
        "id": "CVE-2024-1234",
        "severity": "CRITICAL",
        "score": 9.8,
        "description": "Remote code execution vulnerability"
      }
    ]
  }
}

GET

/api/check/email

Email Risk Assessment

Evaluate the risk associated with an email address. Returns a comprehensive risk score based on multiple factors including data breaches, mail server security, reputation, and pattern analysis. **Risk Factors Analyzed:** - **Data Breaches** - Check if email was exposed in known breaches - **Mail Server Security** - SPF, DKIM, DMARC configuration - **Email Reputation** - Reputation score, suspicious activity, blacklists - **Pattern Analysis** - Typosquatting, disposable emails, suspicious patterns - **Email Validation** - Syntax, MX records validity **Use Cases:** - User registration validation - Fraud prevention - Compliance checks - Lead quality scoring

Parameters

Name	Type	Required	Description
`email`	`string`	Yes	Email address to analyze
`enrichment`	`string`	No	Level of data enrichment: basic, standard, or full (default: `standard`)

Example Request

curl -X GET "https://ismalicious.com/api/check/email?email=user@example.com&enrichment=standard" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "email": "user@example.com",
  "domain": "example.com",
  "localPart": "user",
  "riskScore": {
    "score": 15,
    "level": "safe",
    "factors": [
      {
        "name": "Data Breaches",
        "weight": 0.2,
        "score": 0,
        "contribution": 0,
        "description": "No data breaches found"
      },
      {
        "name": "Mail Server Security",
        "weight": 0.25,
        "score": 10,
        "contribution": 2.5,
        "description": "Mail server security is properly configured"
      },
      {
        "name": "Email Reputation",
        "weight": 0.2,
        "score": 10,
        "contribution": 2,
        "description": "Email reputation: high"
      }
    ],
    "summary": "Appears safe. No significant risk factors identified."
  },
  "confidence": {
    "score": 85,
    "level": "high",
    "factors": [
      "EmailRep.io data available",
      "Mail security data available"
    ],
    "explanation": "High confidence based on 4 data sources."
  },
  "breaches": {
    "found": false,
    "count": 0,
    "sources": []
  },
  "mailSecurity": {
    "spf": "pass",
    "dkim": "unknown",
    "dmarc": "pass",
    "dmarcPolicy": "reject",
    "tls": {
      "supported": true,
      "secure": true
    },
    "score": 90,
    "details": [
      "SPF record configured correctly",
      "DMARC policy set to reject"
    ]
  },
  "reputation": {
    "score": 85,
    "level": "high",
    "suspicious": false,
    "profiles": [
      "linkedin",
      "github"
    ],
    "blacklisted": false,
    "maliciousActivity": false,
    "credentialsLeaked": false,
    "dataBreach": false,
    "disposable": false
  },
  "patterns": {
    "isDisposable": false,
    "isTyposquat": false,
    "hasSuspiciousPattern": false
  },
  "apiVersion": "v1",
  "processingTime": 523,
  "enrichmentLevel": "standard"
}

Search

Search for similar malicious domains

POST

/api/search

Search Keywords

Fuzzy search for similar malicious domains. Useful for finding typosquatting and phishing domains targeting a specific brand.

Parameters

Name	Type	Required	Description
`keywords`	`string`	Yes	Search keywords (e.g., 'paypal', 'microsoft')

Example Request

curl -X POST "https://ismalicious.com/api/search?keywords=paypal" \
  -H "X-API-KEY: YOUR_API_KEY"

Responses

{
  "keywords": "paypal",
  "hits": [
    "paypa1-secure.com",
    "paypal-login-verify.net",
    "secure-paypal-update.org"
  ],
  "total_hits": 127
}

Blocklists

Download threat intelligence blocklists

GET

/api/blocklist/stats

Get Blocklist Stats

Get entry counts and last updated timestamps for all available blocklists. No authentication required.

Example Request

curl -X GET "https://ismalicious.com/api/blocklist/stats"

Responses

{
  "blocklist-ips-critical.txt": {
    "count": 15420,
    "lastUpdated": "2024-12-28T07:00:00.000Z"
  },
  "blocklist-domains-phishing.txt": {
    "count": 89234,
    "lastUpdated": "2024-12-28T07:00:00.000Z"
  },
  "blocklist-domains-malware.txt": {
    "count": 45123,
    "lastUpdated": "2024-12-28T07:00:00.000Z"
  }
}

GET

/api/blocklist/download/{filename}

Download Blocklist

Download a specific blocklist file. **Plan Access:** - FREE: 10% sample (lite version) - BASIC+: Full blocklist **Available Blocklists:** - `blocklist-ips-critical.txt` - Critical severity IPs - `blocklist-ips-all.txt` - All malicious IPs - `blocklist-ips-c2.txt` - C2 server IPs - `blocklist-ips-botnet.txt` - Botnet IPs - `blocklist-domains-phishing.txt` - Phishing domains - `blocklist-domains-malware.txt` - Malware domains - `blocklist-domains-ransomware.txt` - Ransomware domains - `blocklist-domains-all.txt` - All malicious domains

Parameters

Name	Type	Required	Description
`filename`	`string`	Yes	Blocklist filename

Example Request

curl -X GET "https://ismalicious.com/api/blocklist/download/blocklist-domains-phishing.txt" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -o blocklist-domains-phishing.txt

Responses

malicious-domain1.com
malicious-domain2.com
malicious-domain3.com
...

Submit Sources

Submit new threat intelligence sources

POST

/api/submit

Submit Sources

Submit new threat intelligence sources to the community database. **Categories:** malware, phishing, spam, scam, fraud, botnet, ransomware, c2

Request Body

{
  "sources": [
    {
      "name": "Example Threat Feed",
      "type": "ip",
      "url": "https://example.com/threats-ips.txt",
      "category": "malware"
    },
    {
      "name": "Phishing Domains Feed",
      "type": "domain",
      "url": "https://example.com/phishing-domains.txt",
      "category": "phishing"
    }
  ]
}

Example Request

curl -X POST "https://ismalicious.com/api/submit" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{
      "name": "My Threat Feed",
      "type": "domain",
      "url": "https://example.com/feed.txt",
      "category": "phishing"
    }]
  }'

Responses

{
  "message": "Submitted successfully, thanks sharing new sources with us!"
}

Rate Limits

API rate limiting information

API rate limits vary by subscription plan:

PlanRequests/minuteRequests/day

FREE10100

BASIC605,000

PRO30050,000

ENTERPRISEUnlimitedUnlimited

Rate Limit Headers:

Each response includes headers indicating your current usage:

•X-RateLimit-Limit - Maximum requests allowed

•X-RateLimit-Remaining - Requests remaining

•X-RateLimit-Reset - Unix timestamp when limit resets

When Rate Limited:

If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Wait until the reset time or upgrade your plan.

Best Practices:

•Cache responses when possible

•Use batch endpoints for bulk operations

•Implement exponential backoff for retries

•Monitor your usage via the dashboard

Error Codes

API error response formats

All API errors return a consistent JSON format:

{
  "error": "Error Type",
  "message": "Detailed error message"
}

HTTP Status Codes:

CodeDescription

200Success

400Bad Request - Invalid parameters

401Unauthorized - Missing or invalid API key

403Forbidden - Access denied (plan restriction)

404Not Found - Resource doesn't exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error

Common Errors:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Missing required parameter: query"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

429 Rate Limited

{
  "error": "Rate Limited",
  "message": "You have exceeded your rate limit. Please try again later."
}

Ready to Get Started?

Get your free API key and start protecting your infrastructure today.

Get Free API Key Try API Playground