DNS API

https://api.codepunch.com/dns/v2

The DNS API lets you search the broader indexed DNS/gTLD dataset for trademarks, company names, brand names, product names, suspicious terms, nameserver-hosted domain lists, DNS record lookups, PTR, ASN, and observed subdomain data.

Authenticate with /auth/{apikey}/{apisecret} and use the returned token in API requests. Do not make repeated authentication calls; reuse the token while it remains valid for the requesting IP address.

Most list-style DNS endpoints are designed for large result sets. Use keyword filters first, request a count or summary with dm=stats where supported, then page through results with start and limit.

DNS Record Lookups

Use the record lookup endpoints when you need current DNS records for a hostname or reverse DNS for an IP address. These are direct lookup endpoints, not paginated search feeds.

GET/{token}/a/{fqdn}

GET/{token}/aaaa/{fqdn}

GET/{token}/cname/{fqdn}

GET/{token}/mx/{fqdn}

GET/{token}/ns/{fqdn}

GET/{token}/txt/{fqdn}

GET/{token}/ptr/{ip}

# A record lookup
GET .../a/dnlocker.com

{
  "status":      true,
  "hostname":    "dnlocker.com",
  "ip":          "157.245.209.181",
  "dns_records": [
    { "host": "dnlocker.com", "type": "A", "ttl": 198, "ip": "157.245.209.181" }
  ]
}

gTLD Domain Search

GET /{token}/domains

GET /{token}/domains/{nameserver}

Search the DNS API's indexed gTLD domain corpus for trademarks, company names, product names, campaign names, suspicious terms, or other terms of interest. You can also list gTLD domains hosted on a specific nameserver. These endpoints are useful when you need domain names that contain a term, phrase, prefix, suffix, or one of several alternative terms. Large searches should be fetched with pagination.

Trademark, company name, and keyword syntax

brandname contains

Find domains containing a trademark, company name, brand, product name, or other term.

brandname|productname OR

Find domains matching either brand, product, company, or monitoring term.

brandname login AND

Find domains matching both terms, such as a brand plus a suspicious word.

"brandname login" phrase

Find adjacent terms. Quote the value in your shell or HTTP client.

*brandname* partial

Use an asterisk for wildcard-style partial matching.

^brandname* prefix

Use ^ for starts-with and $ for ends-with searches.

Each search term must be at least 3 characters. Very broad trademark, company-name, or product-name searches can contain more results than can be retrieved in one pass, so narrow the search expression before paging through the result set.

Parameters

kw string required for keyword search

Trademark, company name, brand, product, suspicious term, or other search expression using the syntax above.

dm string optional

Use dm=stats to request the total matching record count before fetching pages.

start integer optional

Zero-based starting index for paginated results. Default is 0. Maximum supported start index is 1,000,000.

limit integer optional

Records to return per page. Default is 500. Maximum is 5000.

# Count or summarize matching domains first, where supported.
GET .../domains?kw=brandname&dm=stats

# Fetch the first page.
GET .../domains?kw=brandname&start=0&limit=5000

{
  "status":  true,
  "records": 5000,
  "domains": [
    "examplebrandname.com",
    "brandname-login.net"
  ]
}

Nameservers

GET /{token}/nameservers

Search for nameservers by keyword, or look up the nameservers for a specific domain. Returns nameserver names and the count of gTLD domains hosted on each.

kw string optional

Keyword to search nameserver names by. The same keyword syntax used by domain search applies here.

domain string optional

Find the nameservers for a specific domain. IDNs are supported. Use either kw or domain, not both.

start integer optional

Starting index when paging through a nameserver keyword search.

limit integer optional

Records per page. Use a smaller value while testing and up to 5000 for bulk retrieval.

# Find nameservers containing a keyword.
GET .../nameservers?kw=cloudflare&start=0&limit=500

{
  "status":      true,
  "keyword":     "cloudflare",
  "nameservers": [
    { "nameserver": "ns1.cloudflare.com", "domaincount": 2446 }
  ]
}

GET /{token}/domains/{nameserver}

Returns gTLD domains hosted on a given nameserver. Use kw, dm=stats, start, and limit to summarize, filter, and page through large hosted-domain lists.

GET .../domains/ns1.softnik.com?start=0&limit=5000

{
  "status":  true,
  "ns":      "ns1.softnik.com",
  "records": 2,
  "domains": ["freesoftwaretools.com", "keywordtools.com"]
}

ccTLD Domains

GET /{token}/cctlds

Search observed ccTLD domains for trademarks, company names, product names, suspicious terms, or other terms of interest. This is an experimental beta feature. Coverage is non-comprehensive, so results should be treated as observed DNS API data rather than a complete country-code zone file.

kw string optional

Trademark, company name, brand, product, suspicious term, or other expression to search within observed ccTLD domains.

tld string optional

Filter by registerable TLD. tld=uk returns .uk domains only. Use tld=co.uk for .co.uk specifically.

cc string optional

Two-letter country code. cc=UK returns observed domains under .uk, .co.uk, .net.uk, and other registerable UK suffixes.

start integer optional

Starting index for paginated result sets.

limit integer optional

Records per page. Maximum is 5000.

GET .../cctlds?cc=UK&kw=shop&start=0&limit=500

{
  "status":  true,
  "records": 642,
  "domains": [
    "exampleshop.co.uk",
    "shop-example.uk"
  ]
}

Observed Subdomains

GET /{token}/subdomains/{domain}

Returns observed subdomains for a domain. The data is derived from TLS/SSL certificate hostnames, so it is useful for discovery and monitoring, but it should not be treated as a complete DNS zone listing or as proof that every hostname is currently active.

A valid request can return zero records if no certificate-derived subdomains are available for the domain.

domain string required

The registered domain to search for observed subdomains. IDNs are returned with an ASCII domain field where applicable.

GET .../subdomains/codepunch.com

{
  "status":       true,
  "domain":       "codepunch.com",
  "ascii_domain": "codepunch.com",
  "records":      20,
  "cached":       false,
  "data": [
    "www.codepunch.com",
    "api.codepunch.com",
    "docs.codepunch.com"
  ]
}

Pagination Pattern for DNS API Searches

For large DNS API searches, follow the same pattern used by the Python pagination sample. Keep the same filters while paging through a result set.

1. Authenticate

Call /auth/{apikey}/{apisecret} and use the returned token in subsequent requests.

2. Count

Call the search endpoint with dm=stats where supported to get the total number of matching trademark, company-name, product-name, or other search records.

3. Fetch pages

Request pages with start=0, then increment start by limit until all records are collected.

4. Stop safely

Stop when the returned page is empty, smaller than limit, or the next start would exceed the maximum supported start index.

# Count first.
GET .../domains?kw=brandname&dm=stats

# Then page through results.
GET .../domains?kw=brandname&start=0&limit=5000
GET .../domains?kw=brandname&start=5000&limit=5000
GET .../domains?kw=brandname&start=10000&limit=5000

For a complete runnable example, see the paginated gTLD domain search Python sample. It authenticates, requests the total count, iterates through pages, and writes all collected domains to a text file. You can use the sample to monitor terms such as trademarks, company names, product names, or suspicious campaign words.

ASN Lookup

GET /{token}/asn/{fqdn}

Returns the Autonomous System Number and AS name for an IP address or FQDN. If an FQDN is supplied, the API resolves it to an IP address before returning ASN details. For reverse DNS, use /{token}/ptr/{ip}.

{
  "status":      true,
  "hostname":    "dnlocker.com",
  "ip":          "157.245.209.181",
  "ip_asnumber": "AS14061",
  "ip_asname":   "DIGITALOCEAN-ASN, US"
}