DNS and Subdomains API v2

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

Use the DNS API for direct DNS record lookups, searchable gTLD domain data, nameserver search and mapping, observed ccTLD domains, reverse DNS, IPv4 ASN context, and certificate-derived hostname discovery.

Authenticate with /auth/{apikey}/{apisecret} and use the returned token in API requests. Reuse the token while it remains valid for the requesting IP address instead of authenticating before every request.

Count and pagination fields are endpoint-specific. In particular, records is not a universal total-result field in the DNS API. Use each endpoint's documented dm=stats response where supported.

DNS Record Lookups

These endpoints perform direct DNS lookups. They are not paginated search feeds. A, AAAA, CNAME, MX, NS, and TXT responses place resolver results in dns_records; PTR performs reverse DNS for an IPv4 address.

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/{ipv4}

Representative A-record response

# Request
GET .../a/dnlocker.com

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

gTLD Domain Search

GET/{token}/domains

GET/{token}/domains/{nameserver}

GET/{token}/domains?ns={nameserver}

Search the indexed gTLD domain corpus for terms of interest, or constrain the search to domains associated with a specific nameserver. The nameserver can be supplied as the path value or with ns=.

Verified keyword syntax

brandname term

Search the indexed domain-name field for a term such as a brand, company, product, campaign, or suspicious word.

brandname|productname OR

Match either expression.

"brandname login" phrase

Match the quoted phrase. Preserve the quote characters when sending the query value.

^brandname start

Match at the start of the indexed domain-name field.

brandname$ end

Match at the end of the indexed domain-name field.

Do not use * as a generic wildcard for this search. A blanket three-character minimum also does not apply. Plain unquoted whitespace is not documented here as an AND operator; use the verified forms above when you need predictable matching.

Parameters

kw string optional

Keyword expression using the verified syntax above.

ns string optional

Constrain results to a specific nameserver. Equivalent to using the nameserver as the path segment.

dm enum optional

Use dm=stats to return the matching count in domain_records instead of domain rows.

start integer optional

Zero-based result offset. Default 0. The search path rejects requests when start + limit + 1 exceeds 1,005,001; with limit=5000, start=1000000 is the last full-size page offset.

limit integer optional

Page size. Default 500; use values from 1 through 5000.

Examples

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

# OR search, first page.
GET .../domains?kw=brandname%7Cproductname&start=0&limit=500

# Search only domains associated with one nameserver.
GET .../domains?ns=ns1.softnik.com&kw=brandname&start=0&limit=500

In normal data mode, records is the number of domain IDs returned for the current page, not the total number of matches. Use dm=stats when you need the matching count before paging.

Nameserver Search and Mapping

GET /{token}/nameservers

The nameserver endpoint supports three modes: list nameservers, search nameserver names with kw, or retrieve nameservers associated with a specific domain. Data rows include the nameserver and its associated gTLD domain count.

kw string optional

Search nameserver names. The verified |, quoted phrase, ^, and $ syntax from gTLD domain search also applies here.

domain string optional

Return nameservers associated with one domain. If both domain and kw are supplied, domain takes precedence and the response warns that kw was ignored.

dm enum optional

Use dm=stats for a count response where supported by the selected mode. Nameserver counts use nameserver_records.

sorton enum optional

domaincount or nameserver. Default domaincount.

sortorder enum optional

asc or desc. Default desc.

start integer optional

Starting offset for list mode. For keyword mode, use start=0; multi-page kw pagination is not currently documented as reliable.

limit integer optional

Page size for list or keyword mode. Default 500; use values from 1 through 5000.

Examples

# List nameservers by hosted-domain count.
GET .../nameservers?start=0&limit=100&sorton=domaincount&sortorder=desc

# Search the first keyword page.
GET .../nameservers?kw=cloudflare&start=0&limit=100

# Get nameservers associated with one domain.
GET .../nameservers?domain=example.com

To retrieve domains hosted on a nameserver, use /{token}/domains/{nameserver} or the equivalent /{token}/domains?ns={nameserver} form documented above.

Observed ccTLD Domain Search

GET /{token}/cctlds

Search observed ccTLD domains and optionally filter by an exact registerable TLD or country code. This is an experimental beta dataset with non-comprehensive coverage, so results should not be treated as a complete country-code zone file.

kw string optional

Full-text search value for the observed ccTLD domain-name index. Operator/wildcard syntax is intentionally not documented for this endpoint.

tld string optional

Exact registerable-TLD filter, for example tld=uk or tld=co.uk.

cc string optional

Exact country-code filter, for example cc=UK.

dm enum optional

Use dm=stats to return the matching count in domain_records instead of domain rows.

start integer optional

Starting result offset. Default 0.

limit integer optional

Page size. Default 500; use values from 1 through 5000.

Normal data responses are ordered by the most recently observed rows first. The API does not expose sorton or sortorder controls for this endpoint.

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

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

In normal data mode, records is the number of rows in the current page. Use dm=stats for the matching count.

Certificate-derived Subdomain Discovery

GET /subdomains.php?domain={domain}&t={token}

The supported subdomain endpoint extracts observed hostnames from TLS/SSL certificate common-name and subject-alternative-name data. It is useful for discovery and monitoring, but it is not a DNS zone listing and does not prove that every returned hostname is currently active.

Authenticate first with /auth/{apikey}/{apisecret}, then pass the returned token as t when calling /subdomains.php.

domain string required

Domain suffix to search, for example example.com. Use ASCII/punycode form for IDNs.

t string required

Session token returned by the DNS API authentication endpoint.

limit integer optional

Maximum certificate rows to scan, not a cap on returned hostnames. Default 50000; valid range 1 through 100000.

dm enum optional

Use dm=stats to return records_scanned and count without the subdomains array.

GET .../subdomains.php?domain=codepunch.com&t=YOUR_TOKEN&limit=50000

{
  "status":          true,
  "domain":          "codepunch.com",
  "records_scanned": 8421,
  "count":           3,
  "subdomains": [
    "api.codepunch.com",
    "docs.codepunch.com",
    "www.codepunch.com"
  ]
}

Returned hostnames are deduplicated and sorted. Certificate wildcard names can remain in the output, and the apex domain can also appear when it is present in certificate hostname data. The API does not publish a fixed certificate-history window for this endpoint.

See the DNS Subdomains PHP sample for a complete runnable client.

Counts and Pagination

DNS API response counts are intentionally endpoint-specific. Do not treat records as a universal total-result field.

domains

Normal mode: records is the current page count and domains contains the page. dm=stats returns the matching count as domain_records.

cctlds

Normal mode: records is the current page count. dm=stats returns the matching count as domain_records.

nameservers

Uses nameserver_records for count metadata. List mode supports start/limit; for keyword searches, use start=0 because multi-page keyword pagination is not currently documented as reliable.

subdomains.php

records_scanned reports certificate rows scanned and count reports unique matched hostnames. limit controls the scan, not result-page size.

DNS record lookups

Direct lookup endpoints return dns_records and do not use list pagination.

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

# Then page through the same gTLD query.
GET .../domains?kw=brandname&start=0&limit=5000
GET .../domains?kw=brandname&start=5000&limit=5000
GET .../domains?kw=brandname&start=10000&limit=5000

The paginated gTLD domain search Python sample implements this domains-specific pattern and uses domain_records for the total count.

IPv4 ASN Lookup

GET /{token}/asn/{ipv4-or-hostname}

Returns Autonomous System information for an IPv4 address, or for a hostname that resolves to IPv4. For reverse DNS, use /{token}/ptr/{ipv4}.

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