# WHOIS / RDAP API

See who a domain is registered with, when it was created and when it expires, from the registry itself.

`GET /v1/whois`

- 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 1 hour; send fresh=true to ask the source again.
- MCP tool: `lookup_whois`

Who registered a domain, with which registrar, when it expires, its statuses, nameservers and DNSSEC flag, from the registry's RDAP or WHOIS service, with personal contact data removed. Costs 2 credits per call; cached answers cost the same. Calls that fail upstream (502) are free. Answers are cached for up to 1 hour; 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; reduced to its registrable part. |
| `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 |  |
| `data.unicode` | string | yes |  |
| `data.tld` | string | yes |  |
| `data.tier` | "A" | "B" | "C" | "D" | yes |  |
| `data.source` | "rdap" | "whois" or null | no |  |
| `data.registered` | boolean or null | no |  |
| `data.reduced_from` | string or null | no |  |
| `data.registrar` | object or null | no |  |
| `data.created` | string or null | no |  |
| `data.updated` | string or null | no |  |
| `data.expires` | string or null | no |  |
| `data.age_days` | integer or null | no |  |
| `data.days_to_expiry` | integer or null | no |  |
| `data.statuses` | array of object | no |  |
| `data.statuses.code` | string | yes |  |
| `data.statuses.meaning` | string | yes |  |
| `data.statuses.set_by` | "registrar" | "registry" | "unknown" | yes |  |
| `data.nameservers` | array of string | no |  |
| `data.dnssec` | boolean or null | no |  |
| `data.redacted_fields` | array of string | no |  |
| `data.unpublished_fields` | array of string | no |  |
| `data.unparsed_fields` | array of string | no |  |
| `data.attempts` | array of object | no |  |
| `data.attempts.method` | "rdap" | "rdap-registrar" | "whois" | "whois-referral" | yes |  |
| `data.attempts.server` | string | yes |  |
| `data.attempts.outcome` | string | yes |  |
| `data.attempts.http_status` | integer or null | no |  |
| `data.attempts.elapsed_ms` | integer | yes |  |
| `data.raw` | object or null | no |  |
| `data.retry_after_s` | number 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/whois?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/whois", 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/whois?${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": "whois-lookup",
  "target": "verisign.com",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 2,
  "summary": "verisign.com is registered with CSC Corporate Domains, Inc. until 1 June 2034 (in 2755 days). Transfers are locked and DNSSEC is on.",
  "findings": [],
  "data": {
    "name": "verisign.com",
    "unicode": "verisign.com",
    "tld": "com",
    "tier": "A",
    "source": "rdap",
    "registered": true,
    "registrar": {
      "name": "CSC Corporate Domains, Inc.",
      "iana_id": 299,
      "url": "https://www.cscdbs.example.net",
      "abuse_email": "domainabuse@cscglobal.com",
      "abuse_phone": "+1.8887802723"
    },
    "created": "1995-06-02T04:00:00Z",
    "updated": "2025-02-07T17:08:30Z",
    "expires": "2034-06-01T04:00:00Z",
    "age_days": 11488,
    "days_to_expiry": 2755,
    "statuses": [
      {
        "code": "clientDeleteProhibited",
        "meaning": "The registrar has locked deletion",
        "set_by": "registrar"
      },
      {
        "code": "clientTransferProhibited",
        "meaning": "The registrar has locked transfers",
        "set_by": "registrar"
      },
      {
        "code": "clientUpdateProhibited",
        "meaning": "The registrar has locked changes",
        "set_by": "registrar"
      },
      {
        "code": "serverDeleteProhibited",
        "meaning": "The registry has locked deletion",
        "set_by": "registry"
      },
      {
        "code": "serverTransferProhibited",
        "meaning": "The registry has locked transfers",
        "set_by": "registry"
      },
      {
        "code": "serverUpdateProhibited",
        "meaning": "The registry has locked changes",
        "set_by": "registry"
      }
    ],
    "nameservers": [
      "av1.nstld.com",
      "av2.nstld.com",
      "av3.nstld.com",
      "av4.nstld.com"
    ],
    "dnssec": true,
    "redacted_fields": [],
    "unpublished_fields": [],
    "unparsed_fields": [],
    "attempts": [
      {
        "method": "rdap",
        "server": "rdap.verisign.com",
        "outcome": "found",
        "http_status": 200,
        "elapsed_ms": 12
      },
      {
        "method": "rdap-registrar",
        "server": "rdap.cscglobal.com",
        "outcome": "found",
        "http_status": 200,
        "elapsed_ms": 12
      }
    ],
    "raw": {
      "format": "rdap-json",
      "registry": {
        "objectClassName": "domain",
        "handle": "2703255_DOMAIN_COM-VRSN",
        "ldhName": "VERISIGN.COM",
        "links": [
          {
            "value": "https://rdap.verisign.com/com/v1/domain/verisign.com",
            "rel": "self",
            "href": "https://rdap.verisign.com/com/v1/domain/verisign.com",
            "type": "application/rdap+json"
          },
          {
            "value": "https://rdap.verisign.com/com/v1/domain/verisign.com",
            "rel": "related",
            "href": "https://rdap.cscglobal.com/dbs/rdap-api/v1/domain/VERISIGN.COM",
            "type": "application/rdap+json"
          }
        ],
        "status": [
          "client delete prohibited",
          "client transfer prohibited",
          "client update prohibited",
          "server delete prohibited",
          "server transfer prohibited",
          "server update prohibited"
        ],
        "entities": [
          {
            "objectClassName": "entity",
            "handle": "299",
            "roles": [
              "registrar"
            ],
            "links": [
              {
                "href": "http://cscdbs.com",
                "type": "text/html",
                "value": "https://rdap.cscglobal.com/dbs/rdap-api/v1/",
                "rel": "about"
              }
            ],
            "publicIds": [
              {
                "type": "IANA Registrar ID",
                "identifier": "299"
              }
            ],
            "vcardArray": [
              "vcard",
              [
                [
                  "version",
                  {},
                  "text",
                  "4.0"
                ],
                [
                  "fn",
                  {},
                  "text",
                  "CSC Corporate Domains, Inc."
                ]
              ]
            ],
            "entities": [
              {
                "objectClassName": "entity",
                "roles": [
                  "abuse"
                ],
                "vcardArray": [
                  "vcard",
                  [
                    [
                      "version",
                      {},
                      "text",
                      "4.0"
                    ],
                    [
                      "fn",
                      {},
                      "text",
                      ""
                    ],
                    [
                      "tel",
                      {
                        "type": "voice"
                      },
                      "uri",
                      "tel:8887802723"
                    ],
                    [
                      "email",
                      {},
                      "text",
                      "domainabuse@cscglobal.com"
                    ]
                  ]
                ]
              }
            ]
          }
        ],
        "events": [
          {
            "eventAction": "registration",
            "eventDate": "1995-06-02T04:00:00Z"
          },
          {
            "eventAction": "expiration",
            "eventDate": "2034-06-01T04:00:00Z"
          },
          {
            "eventAction": "last changed",
            "eventDate": "2025-02-07T17:08:30Z"
          },
          {
            "eventAction": "last update of RDAP database",
            "eventDate": "2026-11-14T18:32:50Z"
          }
        ],
        "secureDNS": {
          "delegationSigned": true,
          "dsData": [
            {
              "keyTag": 55204,
              "algorithm": 8,
              "digestType": 2,
              "digest": "206D88653C43D99BF4567BBD7DF9C078DB357F59AA183741024D345723052E88"
            }
          ]
        },
        "nameservers": [
          {
            "objectClassName": "nameserver",
            "ldhName": "AV1.NSTLD.COM"
          },
          {
            "objectClassName": "nameserver",
            "ldhName": "AV2.NSTLD.COM"
          },
          {
            "objectClassName": "nameserver",
            "ldhName": "AV3.NSTLD.COM"
          },
          {
            "objectClassName": "nameserver",
            "ldhName": "AV4.NSTLD.COM"
          }
        ],
        "rdapConformance": [
          "rdap_level_0",
          "icann_rdap_technical_implementation_guide_1",
          "icann_rdap_response_profile_1"
        ],
        "notices": [
          {
            "title": "Terms of Service",
            "description": [
              "Service subject to Terms of Use."
            ],
            "links": [
              {
                "href": "https://www.verisign.com/domain-names/registration-data-access-protocol/terms-service/index.xhtml",
                "type": "text/html",
                "value": "https://rdap.verisign.com/com/v1/domain/verisign.com",
                "rel": "terms-of-service"
              }
            ]
          },
          {
            "title": "Status Codes",
            "description": [
              "For more information on domain status codes, please visit https://icann.org/epp"
            ],
            "links": [
              {
                "href": "https://icann.org/epp",
                "type": "text/html",
                "value": "https://rdap.verisign.com/com/v1/domain/verisign.com",
                "rel": "glossary"
              }
            ]
          },
          {
            "title": "RDDS Inaccuracy Complaint Form",
            "description": [
              "URL of the ICANN RDDS Inaccuracy Complaint Form: https://icann.org/wicf"
            ],
            "links": [
              {
                "href": "https://icann.org/wicf",
                "type": "text/html",
                "value": "https://rdap.verisign.com/com/v1/domain/verisign.com",
                "rel": "help"
              }
            ]
          }
        ]
      },
      "registrar": {
        "objectClassName": "domain",
        "ldhName": "VERISIGN.COM",
        "handle": "synthetic",
        "status": [
          "client transfer prohibited"
        ],
        "events": [
          {
            "eventAction": "registration",
            "eventDate": "1995-06-02T04:00:00Z"
          },
          {
            "eventAction": "expiration",
            "eventDate": "2034-06-01T04:00:00Z"
          },
          {
            "eventAction": "last changed",
            "eventDate": "2025-02-07T17:08:30Z"
          }
        ],
        "entities": [
          {
            "objectClassName": "entity",
            "roles": [
              "registrar"
            ],
            "publicIds": [
              {
                "type": "IANA Registrar ID",
                "identifier": "299"
              }
            ],
            "links": [
              {
                "rel": "about",
                "href": "https://www.cscdbs.example.net",
                "type": "text/html"
              }
            ],
            "vcardArray": [
              "vcard",
              [
                [
                  "version",
                  {},
                  "text",
                  "4.0"
                ],
                [
                  "fn",
                  {},
                  "text",
                  "CSC Corporate Domains, Inc."
                ]
              ]
            ],
            "entities": [
              {
                "objectClassName": "entity",
                "roles": [
                  "abuse"
                ],
                "vcardArray": [
                  "vcard",
                  [
                    [
                      "version",
                      {},
                      "text",
                      "4.0"
                    ],
                    [
                      "fn",
                      {},
                      "text",
                      "Abuse"
                    ],
                    [
                      "tel",
                      {
                        "type": "voice"
                      },
                      "uri",
                      "tel:+1.8887802723"
                    ],
                    [
                      "email",
                      {},
                      "text",
                      "domainabuse@cscglobal.com"
                    ]
                  ]
                ]
              }
            ]
          },
          {
            "objectClassName": "entity",
            "roles": [
              "registrant"
            ],
            "removed": "contact details removed by DNS Super"
          }
        ],
        "nameservers": [
          {
            "objectClassName": "nameserver",
            "ldhName": "AV1.NSTLD.COM",
            "entities": [
              {
                "objectClassName": "entity",
                "roles": [
                  "technical"
                ],
                "removed": "contact details removed by DNS Super"
              }
            ]
          }
        ],
        "secureDNS": {
          "delegationSigned": true
        }
      },
      "scrubbed": true
    }
  },
  "credits_remaining": 498
}
```

## MCP

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

```text
verisign.com is registered with CSC Corporate Domains, Inc. until 1 June 2034 (in 2755 days). Transfers are locked and DNSSEC is on.
Registrar: CSC Corporate Domains, Inc. (IANA 299)
Created 1995-06-02 | expires 2034-06-01 (in 2755 days) | updated 2025-02-07
Status: clientDeleteProhibited (The registrar has locked deletion)
Status: clientTransferProhibited (The registrar has locked transfers)
Status: clientUpdateProhibited (The registrar has locked changes)
Status: serverDeleteProhibited (The registry has locked deletion) +2 more
Nameservers: av1.nstld.com, av2.nstld.com, av3.nstld.com +1 more
DNSSEC: on | source RDAP, tier A
No issues found.
Credits: 2 credits used, 498 remaining | fresh | checked 2026-11-14 10:00 UTC
```
