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. The endpoints the dashboard itself calls, such as the watchlist, coverage and exposure checks, use your signed-in session and are not part of this API.

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:

HeaderDescription
X-RateLimit-LimitMax requests per minute
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetUnix timestamp when the window resets
EndpointRate LimitMax Results
/greyphish/threats120/min5,000
/greyphish/threats/recent240/min500
/greyphish/stats240/min—
/greyphish/domains/{…}/whois60/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 of lookalike domains of the brands in the public feed, detected in Certificate Transparency logs and ICANN zone files.

Query Parameters

ParamTypeDefaultDescription
limitint100Results per page (max 5,000)
offsetint0Pagination offset
daysint365Lookback window in days
brandstring—Filter by target brand (partial match)
levelstring—Filter by threat level: critical, high, medium, low
typestring—Filter by threat type (e.g. typosquat)
sourcestring—Filter by source: CT or CZDS (zone file)
domainstring—Filter by domain (partial match)
min_confidencefloat—Minimum confidence score (0.0–1.0)

Example

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

{
  "success": true,
  "data": {
    "threats": [
      {
        "id": 12345,
        "domain": "harb0urline-bank",
        "tld": "com",
        "full_domain": "harb0urline-bank.com",
        "source_type": "CT",
        "threat_level": "critical",
        "threat_type": "typosquat",
        "target_brand": "Harbourline Bank",
        "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.

ParamTypeDefaultDescription
limitint25Number 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": "acmelogistics-secure.net",
        "threat_level": "high",
        "threat_type": "combosquat",
        "target_brand": "Acme Logistics",
        "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": "Harbourline Bank", "count": 12400 },
      { "brand": "Acme Logistics", "count": 9800 }
    ]
  }
}
GET/greyphish/domains/{domain}/whoismin: greyphish_pro

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

ParamTypeDefaultDescription
domainpath—Fully-qualified domain name (e.g. harb0urline-bank.com)

Example

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

{
  "success": true,
  "data": {
    "domain": "harb0urline-bank.com",
    "cached_at": "2026-03-06T12:00:00Z",
    "registrar": "Example Registrar, 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

FieldTypeDescription
idintInternal ID
domainstringDomain label (without TLD)
tldstringTop-level domain
full_domainstringFull domain as detected
source_typestringCT (Certificate Transparency) or CZDS (zone file)
threat_levelstringcritical, high, medium, or low
threat_typestringSquatting pattern (typosquat, combosquat, etc.)
target_brandstringBrand being impersonated
confidencefloatMatch confidence score (0.0–1.0)
timestampdatetimeISO 8601 detection time
sourcestringSpecific CT log or zone file
industrystringIndustry vertical of the targeted brand
matched_patternstringdnstwist permutation that matched

Webhooks and alert channels

Paid accounts can have every alert delivered as it happens to Slack, Microsoft Teams, PagerDuty or a webhook of their own. Channels are added in the Alerts view, up to five per account. A webhook receives one JSON POST per alert:

{
  "event": "mail_added",
  "matched_domain": "acmelogistlcs.com",
  "full_domain": "login.acmelogistlcs.com",
  "match_type": "domain_permutation",
  "item_id": 42,
  "risk": "high",
  "evidence": ["Mail", "Live site"],
  "timestamp": "2026-11-11T09:00:00+00:00",
  "watched": "acmelogistics.com",
  "link": "https://greyphish.com/?finding=acmelogistlcs.com&item=42",
  "reason": null
}
EventSent when
watchlist_hitA new finding, one whose score rose, or the first certificate for a lookalike found by DNS
went_liveA parked or empty lookalike now serves a site or accepts mail
mail_addedA lookalike that was already up now accepts mail
login_addedA lookalike now serves a page with a password field
copies_siteA lookalike's page now looks like your site or uses its icon, by a measured similarity score
testYou pressed Test on the channel

reason is null except on a watchlist_hit sent because a lookalike that was found by DNS or in a zone file has now been issued its first certificate, where it is "first_certificate". New reasons may be added.

A lookalike alerts at most once per event in seven days. New event names and new fields may be added; ignore the ones you do not handle.

Slack, Teams and webhook channels receive every event. A PagerDuty channel opens an incident only for went_live, mail_added and login_added; watchlist_hit, a first certificate included, and copies_site are not sent to it.

Headers and signature

X-Greyphish-EventThe event name, as in the body
X-Greyphish-DeliveryA UUID for this delivery. It is the same on every retry, so use it to drop duplicates. It is covered by the signature
X-Greyphish-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>

The signature is the HMAC-SHA256 of <t>.<delivery id>.<raw request body>, keyed with the channel's signing secret: t from the signature header, the value of X-Greyphish-Delivery, and the body, joined by dots. The secret is shown once, when the webhook is added or a new one is generated. Compute it over the bytes you received, before parsing them, compare in constant time, and reject a t more than five minutes old. A missing or malformed header is a failed check, not an error:

import hashlib, hmac, time

def verify(secret: str, signature: str | None, delivery_id: str | None, body: bytes) -> bool:
    """signature is X-Greyphish-Signature, delivery_id is X-Greyphish-Delivery."""
    parts = dict(p.strip().split("=", 1) for p in (signature or "").split(",") if "=" in p)
    try:
        t = int(parts.get("t", ""))
    except ValueError:
        return False
    if abs(time.time() - t) > 300:
        return False
    signed = f"{t}.{delivery_id}.".encode() + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), parts.get("v1", "").encode())

New signing secret on a webhook channel replaces its secret; the old one stops verifying at once. A webhook that was saved before signing existed was moved to a channel with a secret nobody has seen: generate a new one to verify its deliveries.

Retries

Answer with any 2xx within 15 seconds, counted from the start of the attempt to the end of your response headers. The response body is not read. A timeout, a connection error, a 429 or a 5xx is retried twice, after 2 seconds and again after 10. An account's deliveries are sent one at a time, so one that is being retried holds back the ones behind it. Any other 4xx, and a redirect, is not retried. A delivery that fails all three attempts is dropped; the finding is still in your dashboard and the daily digest. Once three deliveries in a row have failed, each alert gets a single attempt until one succeeds. After 20 deliveries in a row have failed, the channel is disabled and shows as such in the Alerts view, where it can be turned back on. Private and internal addresses are refused.

Error Codes

CodeHTTPDescription
INVALID_API_KEY401Missing, invalid, or expired API key
ENDPOINT_NOT_ALLOWED403Key does not have access to this endpoint
RATE_LIMIT_EXCEEDED429Per-minute rate limit exhausted
NOT_FOUND404Resource not found (e.g. WHOIS not cached)
INVALID_REQUEST400Missing or invalid parameters
DATABASE_ERROR500Internal server error