Developers
API reference
Read your brands and findings with their evidence, file takedowns, and receive new findings as webhooks. JSON over HTTPS, authenticated with an API key.
Introduction
The API exposes the same data as the dashboard: the brands on your account, every lookalike domain we have found for them with its risk score and evidence, and the takedowns filed against them. All endpoints live under https://supavigent.com/api/v1 and return JSON.
API access is included in the Pro plan. Timestamps are ISO 8601 in UTC; ids are opaque strings.
Authentication
Create a key in the dashboard under Settings → API. Keys start with sv_live_ and are shown once, when created — store it in your secrets manager. Send it as a bearer token on every request:
curl "https://supavigent.com/api/v1/brands" \
-H "Authorization: Bearer sv_live_…"A missing or revoked key returns 401 unauthorized. Keys belong to an account, not a person; revoke one from the same page at any time.
Responses & errors
Successful responses wrap their payload in data: an array for list endpoints, an object for single resources. Errors carry a stable machine-readable code and a human message:
{
"error": {
"code": "not_found",
"message": "No finding with that id on this account."
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter or body field is missing or malformed. |
| 401 | unauthorized | No API key, or the key is unknown or revoked. |
| 403 | plan_required | The account has no plan that includes the API. |
| 403 | account_inactive | The subscription is not active (for example, a failed payment). |
| 403 | forbidden | The key cannot act on this resource. |
| 404 | not_found | No such resource on this account. |
| 409 | owner_profile_incomplete | Takedowns need your rights-holder details — complete them in Settings. |
| 429 | rate_limited | Too many requests for this key. See rate limits. |
| 500 | internal_error | Something failed on our side. Safe to retry. |
Rate limits
Each key may make 600 requests per hour. Every response carries rate-limit headers with your remaining allowance; when it runs out you get 429 rate_limited until the window resets. Back off and retry rather than looping.
List brands
The brands on your account. Use a brand's id to filter findings.
curl "https://supavigent.com/api/v1/brands" \
-H "Authorization: Bearer sv_live_…"{
"data": [
{
"id": "6b0e9a52-…",
"name": "Acme",
"officialDomains": ["acme.com"],
"keywords": ["acme", "acmepay"],
"allowlist": ["acme-partner.com"],
"status": "active",
"lastScanAt": "2026-11-19T06:10:00.000Z",
"createdAt": "2026-11-02T14:31:09.000Z"
}
]
}List findings
Lookalike domains and URLs found for your brands. source is the first source that surfaced it and sources every source that has seen it since: nrd (new registrations), google, bing, ct (Certificate Transparency) and typo (typosquat engine).
riskLevel is critical (75+), high (55+), medium (30+) or low. nextCursor is null on the last page.
Query parameters
- brandIdstring
- Only findings for this brand.
- statusstring
- One of
new,reviewing,takedown,resolved,ignored,allowed. - sourcestring
- Only findings first surfaced by
nrd,google,bing,ctortypo. - minRiskinteger 0–100
- Only findings scoring at least this.
- sortstring
risk(default, highest first) orrecent.- limitinteger 1–200
- Page size. Default 50.
- cursorstring
- The
nextCursorfrom the previous page.
curl "https://supavigent.com/api/v1/findings?minRisk=75&status=new&limit=50" \
-H "Authorization: Bearer sv_live_…"{
"data": [
{
"id": "f3a1c0de-…",
"brandId": "6b0e9a52-…",
"domain": "acme-login.xyz",
"url": "https://acme-login.xyz/",
"source": "nrd",
"sources": ["nrd", "ct"],
"matchKind": "combo",
"matchedTerm": "acme",
"riskScore": 88,
"riskLevel": "critical",
"status": "new",
"firstSeenAt": "2026-11-19T06:10:00.000Z",
"lastSeenAt": "2026-11-19T06:10:00.000Z",
"screenshotUrl": "https://…/screenshot.png",
"signals": {
"state": "live",
"live": true,
"title": "Acme — Sign in",
"registrar": "Example Registrar, Inc.",
"registeredAt": "2026-11-17T00:00:00.000Z",
"onCloudflare": false,
"hasMx": true,
"aiVerdict": "phishing"
}
}
],
"nextCursor": "f2b9…"
}Get a finding
One finding with its full evidence: everything in the list item, plus reasons (the sentences behind the risk score), evidence (the full DNS, live-page, RDAP, hosting and AI-analyst record), serp (the search result when the source was Google or Bing) and the takedowns filed against it.
curl "https://supavigent.com/api/v1/findings/f3a1c0de-…" \
-H "Authorization: Bearer sv_live_…"{
"data": {
"id": "f3a1c0de-…",
"domain": "acme-login.xyz",
"riskScore": 88,
"riskLevel": "critical",
"…": "every list field, plus:",
"reasons": [
"Your name combined with a phishing keyword (login, support, pay…)",
"Page asks for a password",
"Registered 2 days ago",
"Has mail servers — can send email as this domain"
],
"evidence": {
"checkedAt": "2026-11-19T06:11:02.000Z",
"dns": { "a": ["203.0.113.24"], "mx": ["mx1.acme-login.xyz"], "ns": ["ns1.dns-host.example"] },
"resolves": true,
"http": {
"status": 200,
"finalUrl": "https://acme-login.xyz/signin",
"title": "Acme — Sign in",
"hasPasswordField": true,
"hasForm": true,
"parked": false,
"…": "…"
},
"registrar": "Example Registrar, Inc.",
"registeredAt": "2026-11-17T00:00:00.000Z",
"hostOrg": "Example Hosting",
"onCloudflare": false,
"faviconMatchesOfficial": true,
"abuse": [{ "role": "registrar", "email": "[email protected]" }],
"analysis": {
"verdict": "phishing",
"confidence": 0.94,
"reason": "A copy of the Acme sign-in page asking for a password."
}
},
"serp": null,
"takedowns": []
}
}Create takedowns
Files a notice to each channel, in your name, using the rights-holder details in Settings — returns 409 owner_profile_incomplete until they are filled in. Netcraft and Cloudflare are filed by API; the registrar, host and APWG receive an email with reply-to set to you.
Google, Bing and Microsoft only accept signed-in browser forms, so they are not available here; the dashboard prepares those for you to submit.
Body
- kindstringrequired
phishing,trademark,copyright(DMCA, with the 17 U.S.C. §512(c)(3) statements) orimpersonation.- channelsstring[]
- Any of
netcraft,cloudflare,registrar,host,apwg. Channels that don't apply to the finding (for examplecloudflarefor a site not behind it) are skipped.
curl -X POST "https://supavigent.com/api/v1/findings/f3a1c0de-…/takedowns" \
-H "Authorization: Bearer sv_live_…" \
-H "Content-Type: application/json" \
-d '{ "kind": "phishing", "channels": ["netcraft", "registrar", "host", "apwg"] }'{
"data": [
{
"id": "9c41…",
"findingId": "f3a1c0de-…",
"brandId": "6b0e9a52-…",
"channel": "registrar",
"kind": "phishing",
"method": "email",
"status": "queued",
"recipient": "[email protected]",
"externalId": null,
"formUrl": null,
"error": null,
"submittedAt": null,
"resolvedAt": null,
"createdAt": "2026-11-19T06:12:41.000Z"
}
]
}List takedowns
Every takedown on your account, newest first. method is api, email or form; manual means a prepared form is waiting for you to submit it. We recheck reported domains every two days, and when one goes offline its takedowns move to resolved automatically.
Query parameters
- statusstring
queued,submitted,acknowledged,resolved,rejected,failedormanual.- limitinteger 1–300
- How many to return. Default 100.
curl "https://supavigent.com/api/v1/takedowns?status=submitted" \
-H "Authorization: Bearer sv_live_…"{
"data": [
{
"id": "9c41…",
"findingId": "f3a1c0de-…",
"channel": "netcraft",
"kind": "phishing",
"method": "api",
"status": "submitted",
"externalId": "…",
"submittedAt": "2026-11-19T06:12:44.000Z",
"resolvedAt": null
}
]
}Webhooks
Add a webhook URL to a brand's alert settings and we POST a JSON body to it whenever new findings at or above the brand's alert threshold are found. Respond with any 2xx. Slack incoming webhooks are supported separately, with a formatted message.
{
"event": "findings.new",
"brand": { "id": "…", "name": "Acme" },
"findings": [
{
"id": "…",
"domain": "acme-login.xyz",
"url": "https://acme-login.xyz/",
"riskScore": 88,
"riskLevel": "critical",
"source": "nrd",
"matchKind": "combo",
"firstSeenAt": "2026-11-19T06:10:00.000Z",
"dashboardUrl": "https://supavigent.com/findings/…"
}
]
}Questions or a field you need? Email [email protected].