API Reference

Programmatic access to Greyphish threat intelligence data.

Base URL

https://api.greyphish.com/api/v1

Authentication

All requests require a Greyphish API key passed in the X-API-Key header. Keys are provisioned automatically when you subscribe to Greyphish Pro.

curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.greyphish.com/api/v1/greyphish/stats

Rate Limits

Rate limits are per API key and enforced per endpoint. Response headers indicate your current usage:

Header	Description
X-RateLimit-Limit	Max requests per minute
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Endpoint	Rate Limit	Max Results
/greyphish/threats	120/min	5,000
/greyphish/threats/recent	240/min	500
/greyphish/stats	240/min	—
/greyphish/domains/{…}/whois	60/min	—

Response Format

All responses follow a consistent envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "credits_cost": 0,
    "credits_remaining": 9988,
    "rate_limit": 120,
    "rate_limit_remaining": 119,
    "execution_time_ms": 12,
    "result_count": 25,
    "total_results": 4200
  }
}

Errors return:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for this endpoint"
  }
}

Endpoints

GET/greyphish/threatsmin: greyphish_pro

Paginated, filterable threat feed. Returns phishing domains detected from Certificate Transparency logs and ICANN zone files.

Query Parameters

Param	Type	Default	Description
limit	int	100	Results per page (max 5,000)
offset	int	0	Pagination offset
days	int	365	Lookback window in days
brand	string	—	Filter by target brand (partial match)
level	string	—	Filter by threat level: critical, high, medium, low
type	string	—	Filter by threat type (e.g. typosquat)
source	string	—	Filter by source: CT or CZDS
domain	string	—	Filter by domain (partial match)
min_confidence	float	—	Minimum confidence score (0.0–1.0)

Example

curl -H "X-API-Key: sk_live_..." \
  "https://api.greyphish.com/api/v1/greyphish/threats?brand=paypal&level=critical&limit=10"

{
  "success": true,
  "data": {
    "threats": [
      {
        "id": 12345,
        "domain": "paypa1",
        "tld": "com",
        "full_domain": "paypa1.com",
        "source_type": "CT",
        "threat_level": "critical",
        "threat_type": "typosquat",
        "target_brand": "PayPal",
        "confidence": 0.97,
        "timestamp": "2026-03-06T14:22:01Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 420
    }
  }
}

GET/greyphish/threats/recentmin: greyphish_pro

Returns the most recently detected threats, newest first. Designed for dashboard widgets and real-time monitoring.

Param	Type	Default	Description
limit	int	25	Number of threats to return (max 500)

Example

curl -H "X-API-Key: sk_live_..." \
  "https://api.greyphish.com/api/v1/greyphish/threats/recent?limit=5"

{
  "success": true,
  "data": {
    "threats": [
      {
        "id": 45678,
        "full_domain": "arnazon-secure.net",
        "threat_level": "high",
        "threat_type": "combosquat",
        "target_brand": "Amazon",
        "confidence": 0.92,
        "source_type": "CT",
        "timestamp": "2026-03-06T16:01:33Z"
      }
    ]
  }
}

GET/greyphish/statsmin: greyphish_pro

Aggregate statistics across all detected threats. No parameters required.

Example

curl -H "X-API-Key: sk_live_..." \
  "https://api.greyphish.com/api/v1/greyphish/stats"

{
  "success": true,
  "data": {
    "total_threats": 128450,
    "total_scanned": 45000000,
    "by_threat_level": {
      "critical": 3200,
      "high": 18400,
      "medium": 62000,
      "low": 44850
    },
    "by_source_type": {
      "CT": 95000,
      "CZDS": 33450
    },
    "top_brands": [
      { "brand": "PayPal", "count": 12400 },
      { "brand": "Chase", "count": 9800 }
    ]
  }
}

GET/greyphish/domains/{domain}/whoismin: greyphish_pro

Returns cached WHOIS and DNS enrichment for a specific phishing domain. Returns 404 if the domain has not been enriched yet.

Param	Type	Default	Description
domain	path	—	Fully-qualified domain name (e.g. paypa1.com)

Example

curl -H "X-API-Key: sk_live_..." \
  "https://api.greyphish.com/api/v1/greyphish/domains/paypa1.com/whois"

{
  "success": true,
  "data": {
    "domain": "paypa1.com",
    "cached_at": "2026-03-06T12:00:00Z",
    "registrar": "NameCheap, Inc.",
    "country": "US",
    "created_date": "2026-03-01",
    "expires_date": "2027-03-01",
    "nameservers": ["ns1.example.com", "ns2.example.com"],
    "dns_a": ["192.0.2.1"]
  }
}

Threat Object

Field	Type	Description
id	int	Internal ID
domain	string	Domain label (without TLD)
tld	string	Top-level domain
full_domain	string	Full domain as detected
source_type	string	CT (Certificate Transparency) or CZDS (zone file)
threat_level	string	critical, high, medium, or low
threat_type	string	Squatting pattern (typosquat, combosquat, etc.)
target_brand	string	Brand being impersonated
confidence	float	Match confidence score (0.0–1.0)
timestamp	datetime	ISO 8601 detection time
source	string	Specific CT log or zone file
industry	string	Industry vertical of the targeted brand
matched_pattern	string	dnstwist permutation that matched

Error Codes

Code	HTTP	Description
INVALID_API_KEY	401	Missing, invalid, or expired API key
ENDPOINT_NOT_ALLOWED	403	Key does not have access to this endpoint
RATE_LIMIT_EXCEEDED	429	Per-minute rate limit exhausted
NOT_FOUND	404	Resource not found (e.g. WHOIS not cached)
INVALID_REQUEST	400	Missing or invalid parameters
DATABASE_ERROR	500	Internal server error

Dashboard Terms Privacy Contact