Back to API docs

netsh.io API Reference

20 endpoints · v1 · generated September 14, 2026

20 network diagnostic endpoints, one consistent JSON contract. Get a free key at https://netsh.io/developers.

Base URL

https://netsh.io/api/v1

Authentication

An x-api-key header, or an api_key query parameter if you can't set custom headers.

Rate limit

100 requests/day per key, on a rolling 24-hour window. Exceeding it returns a 429.

Versioning

v1 is a stable contract — a breaking change ships as v2, never an in-place edit.

Response envelope

Every endpoint returns the same shape, success or failure:

{
  "ok": true,
  "data": { /* endpoint-specific */ },
  "meta": { "tool": "whois", "version": "v1" }
}
{
  "ok": false,
  "error": "Missing API key — pass it as an x-api-key header or an api_key query parameter.",
  "meta": { "tool": "whois", "version": "v1" }
}

Network & DNS

GET/api/v1/ping

Ping

Round-trip time and packet loss to any host or IP.

ParameterTypeRequiredDescription
hoststringYesHostname or IP address to ping.

Example request

curl "https://netsh.io/api/v1/ping?host=1.1.1.1&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "host": "1.1.1.1",
    "ip": "1.1.1.1",
    "reverseDns": "one.one.one.one",
    "status": "Online",
    "sent": 4,
    "received": 4,
    "lost": 0,
    "lossPercent": 0,
    "min": 4,
    "max": 5,
    "average": 5,
    "text": "Pinging one.one.one.one [1.1.1.1]...\n..."
  },
  "meta": { "tool": "ping", "version": "v1" }
}
GET/api/v1/dns-lookup

DNS Lookup

A, AAAA, MX, TXT, CNAME, NS, and SOA records.

ParameterTypeRequiredDescription
domainstringYesDomain to resolve.
resolverstringNoWhich resolver to query — an ip from the DNS Propagation Checker's named list (8.8.8.8 Google, 1.1.1.1 Cloudflare, 9.9.9.9 Quad9, 208.67.222.222 OpenDNS, 64.6.64.6 Verisign, 94.140.14.14 AdGuard, 223.5.5.5 Alibaba, 4.2.2.1 Level3), or "system" for this server's own default resolver. Omitted or unrecognized defaults to "system".

Example request

curl "https://netsh.io/api/v1/dns-lookup?domain=example.com&resolver=1.1.1.1&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "records": {
      "A": ["104.16.132.229", "104.16.133.229"],
      "AAAA": ["2606:4700::6810:85e5"],
      "MX": [{ "exchange": "mx1.example.com", "priority": 10, "type": "MX" }],
      "TXT": ["v=spf1 include:_spf.example.com -all", "google-site-verification=..."],
      "CNAME": [],
      "NS": ["ns1.example.com", "ns2.example.com"],
      "SOA": [{ "nsname": "ns1.example.com", "hostmaster": "dns.example.com", "serial": 2414136692, "refresh": 10000, "retry": 2400, "expire": 604800, "minttl": 300 }]
    },
    "resolver": { "name": "Cloudflare", "ip": "1.1.1.1" }
  },
  "meta": { "tool": "dns-lookup", "version": "v1" }
}
GET/api/v1/dns-propagation

DNS Propagation

See which public resolvers have picked up a DNS change.

ParameterTypeRequiredDescription
domainstringYesDomain to check.
typestringNoRecord type — A, AAAA, MX, TXT, CNAME, NS, or SOA. Defaults to "A".

Example request

curl "https://netsh.io/api/v1/dns-propagation?domain=example.com&type=A&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "status": "propagated",
    "unreachable": [],
    "resolvers": [
      { "name": "Google", "ip": "8.8.8.8", "countryCode": "US", "records": ["104.16.132.229"], "error": null, "responseTime": 43, "matches": true },
      { "name": "Cloudflare", "ip": "1.1.1.1", "countryCode": "US", "records": ["104.16.132.229"], "error": null, "responseTime": 7, "matches": true },
      { "name": "Level3", "ip": "4.2.2.1", "countryCode": "US", "records": [], "error": "Timed out", "responseTime": 4988, "matches": false }
      // ... 5 more resolvers
    ]
  },
  "meta": { "tool": "dns-propagation", "version": "v1" }
}
GET/api/v1/mx-lookup

MX Lookup

The mail servers that accept email for a domain, in priority order.

ParameterTypeRequiredDescription
domainstringYesDomain to look up.

Example request

curl "https://netsh.io/api/v1/mx-lookup?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "hosts": [
      { "priority": 5, "exchange": "mxa.example.com", "ip": "172.65.169.99", "provider": null },
      { "priority": 10, "exchange": "mxb.example.com", "ip": "172.65.65.66", "provider": null }
    ]
  },
  "meta": { "tool": "mx-lookup", "version": "v1" }
}
GET/api/v1/ip-info

IP Info

Network owner, ISP, and country for any IP address.

ParameterTypeRequiredDescription
targetstringYesIP address or domain (resolved to its first A record).

Example request

curl "https://netsh.io/api/v1/ip-info?target=1.1.1.1&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "ip": "1.1.1.1",
    "source": "live",
    "asn": "AS13335",
    "asName": "Cloudflare, Inc.",
    "asDomain": "cloudflare.com",
    "countryCode": "AU",
    "country": "Australia",
    "continentCode": "OC",
    "continent": "Oceania",
    "resolvedFrom": null
  },
  "meta": { "tool": "ip-info", "version": "v1" }
}
GET/api/v1/asn-lookup

ASN Lookup

The network operator announcing a domain or IP's address block.

ParameterTypeRequiredDescription
targetstringYesIP address or domain.

Example request

curl "https://netsh.io/api/v1/asn-lookup?target=1.1.1.1&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "ip": "1.1.1.1",
    "source": "live",
    "asn": "AS13335",
    "asName": "Cloudflare, Inc.",
    "asDomain": "cloudflare.com",
    "countryCode": "AU",
    "country": "Australia",
    "continentCode": "OC",
    "continent": "Oceania",
    "resolvedFrom": null
  },
  "meta": { "tool": "asn-lookup", "version": "v1" }
}
GET/api/v1/what-is-my-ip

What Is My IP Address

Your public IP, ASN, ISP, and country — detected automatically.

Example request

curl "https://netsh.io/api/v1/what-is-my-ip?api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "ip": "203.0.113.42",
    "asn": "AS7922",
    "asName": "Comcast Cable Communications, LLC",
    "countryCode": "US",
    "country": "United States"
  },
  "meta": { "tool": "what-is-my-ip", "version": "v1" }
}

Security & delivery

GET/api/v1/ssl-checker

SSL Certificate Checker

Issuer, expiry, chain of trust, and SAN coverage.

ParameterTypeRequiredDescription
domainstringYesDomain to check (connects on port 443).

Example request

curl "https://netsh.io/api/v1/ssl-checker?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "status": "valid",
    "commonName": "example.com",
    "subjectAlternativeNames": ["example.com", "www.example.com"],
    "issuer": "WE1",
    "validFrom": "2026-09-05T22:29:39.000Z",
    "expiryDate": "2026-12-04T23:29:33.000Z",
    "daysRemaining": 86,
    "signatureAlgorithm": "ecdsa-with-SHA256",
    "chain": [
      { "commonName": "example.com", "issuer": "WE1", "validFrom": "2026-09-05T22:29:39.000Z", "validTo": "2026-12-04T23:29:33.000Z" },
      { "commonName": "WE1", "issuer": "GTS Root R4", "validFrom": "2023-12-13T09:00:00.000Z", "validTo": "2029-02-20T14:00:00.000Z" }
    ]
  },
  "meta": { "tool": "ssl-checker", "version": "v1" }
}
GET/api/v1/port-checker

Port Checker

Test whether a TCP port is open from the outside.

ParameterTypeRequiredDescription
hoststringYesHostname or IP address.
portnumberYesTCP port number (1-65535).

Example request

curl "https://netsh.io/api/v1/port-checker?host=example.com&port=443&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "host": "example.com",
    "port": 443,
    "status": "open",
    "responseTime": 62
  },
  "meta": { "tool": "port-checker", "version": "v1" }
}
GET/api/v1/http-headers

HTTP Headers Checker

Status, redirects, caching, and security headers.

ParameterTypeRequiredDescription
urlstringYesFull URL to fetch (https:// included).

Example request

curl "https://netsh.io/api/v1/http-headers?url=https://example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "requestedUrl": "https://example.com",
    "statusCode": 200,
    "statusText": "OK",
    "responseTime": 1210,
    "finalUrl": "https://example.com/",
    "redirectChain": ["https://example.com/"],
    "headers": {
      "content-type": "text/html; charset=utf-8",
      "cache-control": "max-age=10",
      "strict-transport-security": "max-age=31536000; includeSubDomains",
      "server": "cloudflare"
      // ... every other response header
    },
    "security": {
      "score": 5,
      "total": 5,
      "present": ["strict-transport-security", "x-frame-options", "x-content-type-options", "referrer-policy", "content-security-policy"],
      "missing": []
    }
  },
  "meta": { "tool": "http-headers", "version": "v1" }
}
GET/api/v1/dns-blacklist-checker

DNS Blacklist Checker

Check whether a host or IP is listed on major spam blocklists.

ParameterTypeRequiredDescription
hoststringYesIPv4 address or domain (resolved to its first IPv4 address).

Example request

curl "https://netsh.io/api/v1/dns-blacklist-checker?host=1.1.1.1&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "host": "1.1.1.1",
    "ip": "1.1.1.1",
    "resolvedFrom": null,
    "results": [
      { "zone": "zen.spamhaus.org", "name": "Spamhaus ZEN", "status": "clean" },
      { "zone": "bl.spamcop.net", "name": "SpamCop", "status": "clean" },
      { "zone": "b.barracudacentral.org", "name": "Barracuda Reputation", "status": "clean" }
      // ... 3 more zones
    ],
    "listedCount": 0,
    "ipv6Only": false
  },
  "meta": { "tool": "dns-blacklist-checker", "version": "v1" }
}

Email authentication

GET/api/v1/spf-checker

SPF Checker

See which mail servers a domain authorizes to send for it.

ParameterTypeRequiredDescription
domainstringYesDomain to check.

Example request

curl "https://netsh.io/api/v1/spf-checker?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "found": true,
    "record": "v=spf1 ip4:192.0.2.0/24 include:_spf.google.com -all",
    "mechanisms": ["ip4:192.0.2.0/24", "include:_spf.google.com", "-all"],
    "multiple": false
  },
  "meta": { "tool": "spf-checker", "version": "v1" }
}
GET/api/v1/dkim-checker

DKIM Checker

Check whether a DKIM key is published for a domain and selector.

ParameterTypeRequiredDescription
domainstringYesDomain to check.
selectorstringYesDKIM selector, e.g. "google" or "selector1".

Example request

curl "https://netsh.io/api/v1/dkim-checker?domain=example.com&selector=google&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "selector": "google",
    "found": false,
    "record": null,
    "keyType": null,
    "hasPublicKey": false
  },
  "meta": { "tool": "dkim-checker", "version": "v1" }
}
GET/api/v1/dmarc-checker

DMARC Checker

See a domain's DMARC policy and where failure reports go.

ParameterTypeRequiredDescription
domainstringYesDomain to check.

Example request

curl "https://netsh.io/api/v1/dmarc-checker?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "found": true,
    "record": "v=DMARC1; p=reject; pct=100; rua=mailto:rua@example.com",
    "tags": { "v": "DMARC1", "p": "reject", "pct": "100", "rua": "mailto:rua@example.com" }
  },
  "meta": { "tool": "dmarc-checker", "version": "v1" }
}
GET/api/v1/dnssec-test

DNSSEC Test

Check whether DNSSEC is configured and actually validating.

ParameterTypeRequiredDescription
domainstringYesDomain to check.

Example request

curl "https://netsh.io/api/v1/dnssec-test?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "keyCount": 3,
    "validated": true,
    "status": "enabled"
  },
  "meta": { "tool": "dnssec-test", "version": "v1" }
}
GET/api/v1/mailhealth-check

Mail Health Check

MX, SPF, DMARC, DKIM, and blacklist status for a domain in one pass, with a plain verdict.

ParameterTypeRequiredDescription
domainstringYesDomain to check.

Example request

curl "https://netsh.io/api/v1/mailhealth-check?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "verdict": {
      "status": "critical",
      "headline": "1 problem found",
      "summary": "Trouble with: Blacklist Status."
    },
    "checks": [
      { "id": "mx", "label": "Mail Servers (MX)", "status": "ok", "summary": "4 mail servers, lowest priority mxa.example.net",
        "details": { "hosts": [
          { "priority": 5, "exchange": "mxa.example.net", "ip": "172.65.169.99", "provider": null },
          { "priority": 5, "exchange": "mxb.example.net", "ip": "172.65.65.66", "provider": null },
          { "priority": 10, "exchange": "mxc.example.net", "ip": "141.101.90.40", "provider": null },
          { "priority": 10, "exchange": "mxd.example.net", "ip": "172.65.64.105", "provider": null }
        ], "total": 4, "nullMx": false } },
      { "id": "spf", "label": "SPF Record", "status": "ok", "summary": "SPF record found with 9 mechanisms.",
        "details": { "record": "v=spf1 ip4:199.15.212.0/22 include:_spf.example.com -all", "recordCount": 1, "mechanismCount": 9 } },
      { "id": "dmarc", "label": "DMARC Policy", "status": "ok", "summary": "Policy is \"reject\" — failing mail is rejected.",
        "details": { "record": "v=DMARC1; p=reject; pct=100; rua=mailto:dmarc@example.com", "policy": "reject" } },
      { "id": "dkim", "label": "DKIM Signing", "status": "ok", "summary": "DKIM key published under selector \"s1\" (and 1 more).",
        "details": { "selectorsFound": ["s1", "k1"] } },
      { "id": "blacklist", "label": "Blacklist Status", "status": "critical", "summary": "Listed: 172.65.169.99 on Spamhaus ZEN.",
        "details": { "checkedIps": 4, "listedIps": 1, "cleanIps": 3,
          "results": [
            { "ip": "172.65.169.99", "listed": true, "listedOn": ["Spamhaus ZEN"] },
            { "ip": "172.65.65.66", "listed": false, "listedOn": [] },
            { "ip": "141.101.90.40", "listed": false, "listedOn": [] },
            { "ip": "172.65.64.105", "listed": false, "listedOn": [] }
          ] } }
    ]
  },
  "meta": { "tool": "mailhealth-check", "version": "v1" }
}

Other

GET/api/v1/abuse-contact-lookup

Abuse Contact Lookup

Find a domain's registrar abuse contact, straight from WHOIS.

ParameterTypeRequiredDescription
domainstringYesDomain to look up.

Example request

curl "https://netsh.io/api/v1/abuse-contact-lookup?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "matchedDomain": null,
    "registrar": "Example Registrar, Inc.",
    "email": "registrar-abuse@example.com",
    "phone": "+1.5555550123",
    "found": true
  },
  "meta": { "tool": "abuse-contact-lookup", "version": "v1" }
}
GET/api/v1/whois

WHOIS

Registrar, registration dates, and name servers.

ParameterTypeRequiredDescription
domainstringYesDomain to look up.

Example request

curl "https://netsh.io/api/v1/whois?domain=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "notFound": false,
    "source": "WHOIS",
    "matchedDomain": null,
    "registrar": "Example Registrar, Inc.",
    "creationDate": "2009-02-17T22:07:54Z",
    "expiryDate": "2033-02-17T22:07:54Z",
    "updatedDate": "2024-01-09T16:45:28Z",
    "nameServers": ["ns1.example.com", "ns2.example.com"],
    "daysUntilExpiry": 2353,
    "message": null,
    "raw": "   Domain Name: EXAMPLE.COM\n   Registrar: Example Registrar, Inc.\n   ..."
  },
  "meta": { "tool": "whois", "version": "v1" }
}
GET/api/v1/open-graph-checker

Open Graph Checker

Preview a URL's share card — Open Graph and Twitter Card tags.

ParameterTypeRequiredDescription
urlstringYesFull URL to fetch (https:// included).

Example request

curl "https://netsh.io/api/v1/open-graph-checker?url=https://example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "requestedUrl": "https://example.com",
    "finalUrl": "https://example.com/",
    "statusCode": 200,
    "fetched": true,
    "title": "Example — Build for the agent era",
    "og": {
      "title": "Example — Build for the agent era",
      "description": "Welcome to Example.",
      "image": "https://example.com/preview.png",
      "url": "https://example.com/",
      "type": "website",
      "site_name": null
    },
    "twitter": {
      "card": "summary_large_image",
      "title": "Example — Build for the agent era",
      "description": "Welcome to Example.",
      "image": "https://example.com/preview.png",
      "site": null
    }
  },
  "meta": { "tool": "open-graph-checker", "version": "v1" }
}
GET/api/v1/website-health-check

Website Health Check

DNS, ping, HTTP, SSL, and port checks against a domain in one pass, with a plain verdict.

ParameterTypeRequiredDescription
targetstringYesDomain or URL to check.

Example request

curl "https://netsh.io/api/v1/website-health-check?target=example.com&api_key=YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "targetUrl": "https://example.com/",
    "ip": "172.66.147.243",
    "verdict": {
      "status": "warning",
      "headline": "Mostly healthy",
      "summary": "Worth a look: Security headers."
    },
    "checks": [
      { "id": "dns", "label": "IP address", "status": "ok", "summary": "172.66.147.243",
        "details": { "ip": "172.66.147.243" } },
      { "id": "location", "label": "Location", "status": "ok", "summary": "United States",
        "details": { "countryCode": "US" } },
      { "id": "organization", "label": "Organization", "status": "ok", "summary": "Cloudflare, Inc.",
        "details": { "orgDomain": "cloudflare.com" } },
      { "id": "ping", "label": "Ping", "status": "ok", "summary": "32ms average round trip, no packet loss.",
        "details": { "avgRoundTripMs": 32, "packetLossPercent": 0 } },
      { "id": "latency", "label": "Latency", "status": "ok", "summary": "119ms response time.",
        "details": { "totalMs": 119, "breakdown": { "dnsMs": 11, "tcpMs": 20, "tlsMs": 53, "remainingMs": 35, "totalMs": 119 } } },
      { "id": "http", "label": "HTTP response", "status": "ok", "summary": "Server returned 200 OK.",
        "details": { "statusCode": 200, "statusText": "OK", "cloudflareBlocked": false } },
      { "id": "redirects", "label": "Redirects", "status": "ok", "summary": "No redirects — this is the final destination.",
        "details": { "hops": [] } },
      { "id": "ssl", "label": "SSL certificate", "status": "ok", "summary": "Valid — 46 days remaining.",
        "details": { "daysRemaining": 46, "percentRemaining": 13 } },
      { "id": "security", "label": "Security headers", "status": "warning", "summary": "0/5 common security headers present.",
        "details": { "present": 0, "total": 5 } },
      { "id": "protocol", "label": "HTTP protocol", "status": "ok", "summary": "HTTP/2 negotiated.",
        "details": { "protocol": "HTTP/2" } },
      { "id": "compression", "label": "Compression", "status": "ok", "summary": "Brotli enabled.",
        "details": { "encoding": "br" } },
      { "id": "ports", "label": "Ports (80 / 443)", "status": "ok", "summary": "HTTP (80): Open · HTTPS (443): Open",
        "details": { "ports": [{ "port": 80, "protocol": "http", "status": "open" }, { "port": 443, "protocol": "https", "status": "open" }] } }
    ]
  },
  "meta": { "tool": "website-health-check", "version": "v1" }
}