Developer API docs for authenticity verdicts and score advisory

The external developer API is intentionally separate from the paid-user account API. It gives approved developers API-key protected access to domain authenticity verdicts and security score advisory statements.

External developer keys do not work on the paid-user /api/v1 account API and do not return tracked-domain history, signed-in reports, scan ownership IDs or paid evidence packs.

MyDomainRisk runs two different depths of check, and this API gives you the shallower one. The difference is not a limit on how many you may run — it is a difference in how much analysis is done and how much detail comes back.

What the quick check does not do

• It does not explain a finding. You get a title and a severity, not the analysis behind it, the remediation steps, or which sources contributed.
• Its score is a floor. It reads a lighter exposure index, so a full scan can return the same score or a higher one, never a lower one. When that applies, coverage_note says so in the response — do not present the number without it.
• It may report a provisional authenticity verdict. When enrichment_status is pending, two slower signals are still running and the verdict may still change. Nothing is pushed to you when they finish. Request the same domain again shortly and you will be served the enriched answer, which reports completed. A not_applicable verdict needed no slow signal and will not change however often you ask. This is exactly how the website behaves — a visitor is not notified either.
• It may not have read the homepage. homepage.reviewed tells you whether it did, and homepage.blocked_by names what stopped it. “Nothing found” and “the page could not be fetched” are different answers and must not be shown the same way.
• Results are cached for up to 20 minutes and there is no force-refresh. A domain that changed in the last few minutes may not show it yet.

Because it is the same check a visitor can run, it carries the same allowance: five per hour. It does not consume the account's daily check allowance, which belongs to full scans.

These are outcome-level answers for vetting and triage. They are not a substitute for a full scan of a domain you are responsible for.

The full API contract is published as an OpenAPI 3.1 document. Validate responses in your CI or generate typed clients from it rather than transcribing the tables below.

curl -sS https://mydomainrisk.com/openapi.json

The same document is reachable from the API host, which redirects to the address above:

curl -sSL https://api.mydomainrisk.com/api/developer/v1/openapi.json

It carries the exact permitted values for every field with a fixed set of answers — verdicts, grades, score buckets and finding severities — so nothing on this page needs to be inferred from example responses.

Developer API keys are available on every plan, including Free. A key carries its owner's account and can do what that account can do — no more. Create a Developer API - authenticity and score advisory key from the account area and send it as a Bearer token.

Authorization: Bearer mdr_live_<id>_<secret>

Use developer keys only from server-side code. Do not put them in browser JavaScript, mobile apps, public repositories or client-side logs.

Validate a key before building against it:

GET https://api.mydomainrisk.com/api/developer/v1/me
Authorization: Bearer mdr_live_<id>_<secret>

{
  "api": "developer",
  "version": "v1",
  "scope": "developer_peek",
  "tier": "pro",
  "capabilities": [
    { "operation_id": "getDeveloperCapabilities", "method": "GET", "path": "/me" },
    { "operation_id": "checkDomainSecurity", "method": "GET", "path": "/peek/security" },
    { "operation_id": "checkDomainAuthenticity", "method": "GET", "path": "/peek/authenticity" }
  ],
  "limits": {
    "requests_per_minute_per_key": 120,
    "requests_per_minute_per_ip": 60,
    "requests_per_hour_per_subnet": 150,
    "cache_max_age_seconds": 1200
  },
  "entitlements": {
    "security_score_advisory": true,
    "authenticity_verdict": true,
    "account_data": false,
    "force_refresh": false,
    "consumes_account_daily_allowance": false
  }
}

The capability response deliberately contains no account email or customer data.

If you need API access and do not have an account, or want to discuss a partner arrangement, contact support@mydomainrisk.com.

GET https://api.mydomainrisk.com/api/developer/v1/peek/security?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

Example response:

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "score": 82,
  "grade": "B",
  "score_summary": {
    "bucket": "good",
    "label": "Good"
  },
  "findings": [
    {
      "title": "DMARC policy could be stronger",
      "severity": "medium"
    }
  ],
  "total_findings": 1,
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 842
}

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

You can include optional brand context when the expected organisation name is known:

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com&expected_brand=Example%20Ltd
Authorization: Bearer mdr_live_<id>_<secret>

Example response:

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "verdict": "genuine",
  "findings": [],
  "total_findings": 0,
  "factual": {
    "resolves": true,
    "registrar": "Example Registrar Ltd",
    "age_days": 10950,
    "has_tls": true
  },
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 936
}

Authenticity verdict values:

For simple traffic-light integrations, map genuine and probablyLegit to pass, uncertain and suspicious to review, and malicious to fail.

Security score advisory fields

Branch on score_summary.bucket rather than comparing score against your own thresholds. The bucket is part of the contract; a threshold you pick yourself is not, and will drift from ours without any error to tell you.

Authenticity verdict fields

Results are cached for up to 20 minutes. There is no force-refresh option on the developer API; present results as a recent advisory rather than a permanent decision for domains that may have just changed.

Developer API requests are limited to 120 requests per minute per key, 60 per minute per IP and 150 per hour per subnet.

The allowance that actually binds a check is five per hour, per IP — the same allowance a visitor gets running the same check on our website. The per-minute figures above are burst guards sitting on top of it. /me reports it as peeks_per_hour_per_ip, and reading /me does not count against it.

These checks do not consume the account's daily check allowance. That allowance belongs to full scans, which are deeper and are a different thing entirely.

Every failure returns the same JSON shape, on every path and at every status. Branch on error.code, not on the message text:

{ "error": { "code": "rate_limited", "message": "...", "retry_after_seconds": 30 } }

Treat this list as the codes worth handling individually, not as a closed set: recognise these and fall back on the HTTP status for anything else, so a new code never breaks your integration.

A 429 carries a Retry-After header as well as the field above. Back off on it rather than on a fixed interval.

The API is for legitimate business, security, fraud-prevention, customer-protection and compliance workflows. MyDomainRisk performs non-intrusive external analysis only.

The developer API receives the domain and request metadata needed to provide the service, authenticate the caller, enforce limits and protect the platform. MyDomainRisk does not sell API submission data.

Developer API results may be cached and counted in aggregate telemetry according to the same public domain-check operating model and the MyDomainRisk privacy policy. For privacy questions, contact support@mydomainrisk.com.