# DNSSEC and nameservers API

Check a domain's DNSSEC chain of trust and every nameserver, straight from the registry and the servers themselves.

`GET /v1/dnssec`

- Price: Costs 2 credits per call; cached answers cost the same. Calls that fail upstream (502) are free.
- Cache: Answers are cached for up to 5 minutes; send fresh=true to ask the source again.
- MCP tool: `check_dnssec`

The delegation at the parent, every nameserver's answers over UDP and TCP, serials and glue, and the DNSSEC chain of trust with the reason when it breaks. Costs 2 credits per call; cached answers cost the same. Calls that fail upstream (502) are free. Answers are cached for up to 5 minutes; send fresh=true to ask the source again. A retry with the same `X-Request-Id` returns the stored result of the first call for 24 hours without charging again, marked with the `X-Replayed: true` header.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | A domain or URL; the zone it belongs to is checked. |
| `fresh` | boolean | no | Skip the cache and ask the source again; costs the same. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes |  |
| `target` | string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `fetched_at` | string | no |  |
| `cached` | boolean | no |  |
| `credits_used` | integer | no | Credits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in |
| `summary` | string | yes |  |
| `score` | integer or null | no |  |
| `findings` | array of object | no |  |
| `credits_remaining` | integer | yes | Your balance after this call. It can be below zero after a refund; free tools still work then |
| `data` | object | yes | This tool's result |
| `data.name` | string | yes | The name asked about, in ASCII |
| `data.unicode` | string | yes |  |
| `data.zone` | string | yes | The zone checked: the name itself or the zone it lives in |
| `data.parent` | string | yes |  |
| `data.dnssec` | "secure" | "insecure" | "bogus" | "indeterminate" | yes |  |
| `data.extended_errors` | array of object | yes |  |
| `data.extended_errors.code` | integer | yes |  |
| `data.extended_errors.text` | string | yes |  |
| `data.chain` | array of object | yes |  |
| `data.chain.zone` | string | yes |  |
| `data.chain.signed` | boolean or null | yes | A DS record for this zone exists at its parent |
| `data.chain.secure` | boolean or null | yes | The resolver validated that DS answer |
| `data.ds` | array of object | yes |  |
| `data.ds.key_tag` | integer | yes |  |
| `data.ds.algorithm` | integer | yes |  |
| `data.ds.algorithm_name` | string | yes |  |
| `data.ds.digest_type` | integer | yes |  |
| `data.ds.matches_key` | boolean | yes |  |
| `data.dnskeys` | array of object | yes |  |
| `data.dnskeys.key_tag` | integer | yes |  |
| `data.dnskeys.role` | "ksk" | "zsk" | "csk" | yes |  |
| `data.dnskeys.algorithm` | integer | yes |  |
| `data.dnskeys.algorithm_name` | string | yes |  |
| `data.dnskeys.bits` | integer or null | no |  |
| `data.dnskeys.revoked` | boolean | yes |  |
| `data.dnskeys.servers` | array of string | yes | Addresses that served this key |
| `data.signatures` | array of object | yes |  |
| `data.signatures.covers` | string | yes |  |
| `data.signatures.key_tag` | integer | yes |  |
| `data.signatures.expiration` | string | yes |  |
| `data.signatures.expires_in_days` | integer | yes |  |
| `data.signatures.state` | "valid" | "invalid" | "expired" | "not_yet_valid" | "no_key" | "unsupported_algorithm" | yes |  |
| `data.signatures.servers` | array of string | yes |  |
| `data.denial` | object | yes |  |
| `data.denial.kind` | "nsec" | "nsec3" | "compact" | "none" | "unknown" | yes |  |
| `data.denial.nsec3_iterations` | integer or null | no |  |
| `data.denial.nsec3_salt_length` | integer or null | no |  |
| `data.denial.nsec3_opt_out` | boolean or null | no |  |
| `data.parent_ns` | array of string | yes |  |
| `data.parent_ns_ttl` | integer or null | no |  |
| `data.child_ns` | array of string | yes |  |
| `data.nameservers` | array of object | yes |  |
| `data.nameservers.name` | string | yes |  |
| `data.nameservers.in_parent` | boolean | yes |  |
| `data.nameservers.in_child` | boolean | yes |  |
| `data.nameservers.glue` | array of string | yes |  |
| `data.nameservers.addresses` | array of string | yes |  |
| `data.nameservers.status` | "ok" | "lame" | "unreachable" | "no_address" | "untested" | yes |  |
| `data.nameservers.servers` | array of object | yes |  |
| `data.serials` | object | yes | Serial number -> addresses serving it |
| `data.ipv6_checked` | boolean | yes |  |
| `data.min_ttl` | integer or null | no |  |

## Errors

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `402` Balance below the call's price (`insufficient_credits`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)
- `502` Every upstream source failed; not charged (`source_unavailable`). A Retry-After header says how long to wait when the source asked us to

## Example

```sh
curl "https://api.dnssuper.com/v1/dnssec?domain=example.com" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```python
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.get("/v1/dnssec", params={
    "domain": "example.com",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])
```

```ts
const response = await fetch(`https://api.dnssuper.com/v1/dnssec?${new URLSearchParams({"domain":"example.com"})}`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
```

Example response:

```json
{
  "tool": "dnssec-checker",
  "target": "example.com",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 2,
  "summary": "example.com is DNSSEC-signed and validates, and 2 of 2 nameservers answer correctly.",
  "findings": [
    {
      "id": "dnssec.nsec3",
      "severity": "info",
      "title": "Your zone uses NSEC3",
      "detail": "Answers for missing names carry NSEC3 records.",
      "fix": "Nothing to do."
    },
    {
      "id": "dnssec.secure",
      "severity": "pass",
      "title": "DNSSEC is set up correctly",
      "detail": "The chain of trust from the root down to example.com validates.",
      "fix": "Nothing to do."
    },
    {
      "id": "ns.consistent",
      "severity": "pass",
      "title": "Your nameservers all answer and agree",
      "detail": "2 nameservers answered authoritatively with the same serial.",
      "fix": "Nothing to do."
    }
  ],
  "data": {
    "name": "example.com",
    "unicode": "example.com",
    "zone": "example.com",
    "parent": "com",
    "parent_ns": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "parent_ns_ttl": 172800,
    "child_ns": [
      "ns1.example.com",
      "ns2.example.com"
    ],
    "chain": [
      {
        "zone": "com",
        "signed": true,
        "secure": true
      },
      {
        "zone": "example.com",
        "signed": true,
        "secure": true
      }
    ],
    "dnssec": "secure",
    "extended_errors": [],
    "ds": [
      {
        "key_tag": 65437,
        "algorithm": 13,
        "algorithm_name": "ECDSAP256SHA256",
        "digest_type": 2,
        "matches_key": true
      }
    ],
    "dnskeys": [
      {
        "key_tag": 65437,
        "role": "csk",
        "algorithm": 13,
        "algorithm_name": "ECDSAP256SHA256",
        "bits": 256,
        "revoked": false,
        "servers": [
          "192.0.2.1",
          "198.51.100.2"
        ]
      }
    ],
    "signatures": [
      {
        "covers": "DNSKEY",
        "key_tag": 65437,
        "expiration": "2026-11-28T10:00:00Z",
        "expires_in_days": 14,
        "state": "valid",
        "servers": [
          "192.0.2.1",
          "198.51.100.2"
        ]
      },
      {
        "covers": "SOA",
        "key_tag": 65437,
        "expiration": "2026-11-28T10:00:00Z",
        "expires_in_days": 14,
        "state": "valid",
        "servers": [
          "192.0.2.1",
          "198.51.100.2"
        ]
      }
    ],
    "denial": {
      "kind": "nsec3",
      "nsec3_iterations": 0,
      "nsec3_salt_length": 0,
      "nsec3_opt_out": false
    },
    "nameservers": [
      {
        "name": "ns1.example.com",
        "in_parent": true,
        "in_child": true,
        "glue": [
          "192.0.2.1"
        ],
        "addresses": [
          "192.0.2.1"
        ],
        "status": "ok",
        "servers": [
          {
            "address": "192.0.2.1",
            "family": "ipv4",
            "udp": true,
            "tcp": true,
            "authoritative": true,
            "serial": 2026111401,
            "elapsed_ms": 12,
            "open_resolver": false,
            "dnskey_tags": [
              65437
            ]
          }
        ]
      },
      {
        "name": "ns2.example.com",
        "in_parent": true,
        "in_child": true,
        "glue": [
          "198.51.100.2"
        ],
        "addresses": [
          "198.51.100.2"
        ],
        "status": "ok",
        "servers": [
          {
            "address": "198.51.100.2",
            "family": "ipv4",
            "udp": true,
            "tcp": true,
            "authoritative": true,
            "serial": 2026111401,
            "elapsed_ms": 12,
            "open_resolver": false,
            "dnskey_tags": [
              65437
            ]
          }
        ]
      }
    ],
    "serials": {
      "2026111401": [
        "192.0.2.1",
        "198.51.100.2"
      ]
    },
    "ipv6_checked": false,
    "min_ttl": 3600
  },
  "credits_remaining": 498
}
```

## MCP

```json
{
  "tool": "check_dnssec",
  "arguments": {
    "domain": "example.com"
  }
}
```

```text
example.com is DNSSEC-signed and validates, and 2 of 2 nameservers answer correctly.
DNSSEC: secure (zone example.com, parent com)
DS: key 65437, algorithm 13 (ECDSAP256SHA256), digest type 2, matches a served key
Keys: 65437 csk ECDSAP256SHA256 256 bits
Soonest signature expiry: 2026-11-28 (in 14 days)
ns1.example.com: ok, serial 2026111401, TCP yes
ns2.example.com: ok, serial 2026111401, TCP yes
- info: Your zone uses NSEC3
2 checks passed
Credits: 2 credits used, 498 remaining | fresh | checked 2026-11-14 10:00 UTC
```
