API Reference
Programmatic access to Greyphish threat intelligence data.
Base URL
https://api.greyphish.com/api/v1Authentication
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/statsRate 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
/greyphish/threatsmin: greyphish_proPaginated, filterable threat feed of lookalike domains of the brands in the public feed, detected in 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 (zone file) |
| 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=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
}
}
}/greyphish/threats/recentmin: greyphish_proReturns 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": "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"
}
]
}
}/greyphish/statsmin: greyphish_proAggregate 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 }
]
}
}/greyphish/domains/{domain}/whoismin: greyphish_proReturns cached WHOIS and DNS enrichment for a specific lookalike domain. Returns 404 if the domain has not been enriched yet.
| Param | Type | Default | Description |
|---|---|---|---|
| domain | path | — | 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
| 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 |
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
}| Event | Sent when |
|---|---|
| watchlist_hit | A new finding, one whose score rose, or the first certificate for a lookalike found by DNS |
| went_live | A parked or empty lookalike now serves a site or accepts mail |
| mail_added | A lookalike that was already up now accepts mail |
| login_added | A lookalike now serves a page with a password field |
| copies_site | A lookalike's page now looks like your site or uses its icon, by a measured similarity score |
| test | You 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-Event | The event name, as in the body |
| X-Greyphish-Delivery | A 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-Signature | t=<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
| 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 |