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.

https://supavigent.com/api/v1600 requests / hour / 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:

Authenticated 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:

Error404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "No finding with that id on this account."
  }
}
StatusCodeMeaning
400invalid_requestA parameter or body field is missing or malformed.
401unauthorizedNo API key, or the key is unknown or revoked.
403plan_requiredThe account has no plan that includes the API.
403account_inactiveThe subscription is not active (for example, a failed payment).
403forbiddenThe key cannot act on this resource.
404not_foundNo such resource on this account.
409owner_profile_incompleteTakedowns need your rights-holder details — complete them in Settings.
429rate_limitedToo many requests for this key. See rate limits.
500internal_errorSomething 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

GET/brands

The brands on your account. Use a brand's id to filter findings.

Request
curl "https://supavigent.com/api/v1/brands" \
  -H "Authorization: Bearer sv_live_…"
Response200 OK
{
  "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

GET/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, ct or typo.
minRiskinteger 0–100
Only findings scoring at least this.
sortstring
risk (default, highest first) or recent.
limitinteger 1–200
Page size. Default 50.
cursorstring
The nextCursor from the previous page.
Request
curl "https://supavigent.com/api/v1/findings?minRisk=75&status=new&limit=50" \
  -H "Authorization: Bearer sv_live_…"
Response200 OK
{
  "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

GET/findings/{id}

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.

Request
curl "https://supavigent.com/api/v1/findings/f3a1c0de-…" \
  -H "Authorization: Bearer sv_live_…"
Response200 OK
{
  "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

POST/findings/{id}/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) or impersonation.
channelsstring[]
Any of netcraft, cloudflare, registrar, host, apwg. Channels that don't apply to the finding (for example cloudflare for a site not behind it) are skipped.
Request
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"] }'
Response201 Created
{
  "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

GET/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, failed or manual.
limitinteger 1–300
How many to return. Default 100.
Request
curl "https://supavigent.com/api/v1/takedowns?status=submitted" \
  -H "Authorization: Bearer sv_live_…"
Response200 OK
{
  "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.

findings.newPOST to your URL
{
  "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].