{ "openapi": "3.0.3", "info": { "title": "NetTrace API", "version": "1.2.0", "description": "Official API for NetTrace DNS tools: DNS lookup, email validation, domain security checks, and spam/DNSBL checks.\n\nv1.1/1.2 (2026-10-04): backwards compatible. Requests may also be sent as application/x-www-form-urlencoded or JSON. dns-check queries every resolver for real, in parallel, with a per-resolver timeout, and adds the optional fields status, rtt_ms and cached per resolver. Add ?stream=1 (or Accept: application/x-ndjson) to receive one JSON line per resolver as soon as it answers. Rate limit: on average 1 request/s per IP with bursts up to 30 (HTTP 429 with Retry-After). HTTP 503 means the server is temporarily busy." }, "servers": [ { "url": "https://api.nettrace.eu/v1.0" } ], "tags": [ { "name": "DNS Tools", "description": "NetTrace DNS tools: DNS checks, email validation, security analysis, and spam/DNSBL checks." } ], "paths": { "/dns-check": { "post": { "tags": [ "DNS Tools" ], "summary": "Perform a DNS record check across multiple resolvers.", "operationId": "dnsCheck", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DnsCheckRequest" }, "encoding": { "domain": { "style": "form" }, "recordType": { "style": "form" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DnsCheckRequest" }, "encoding": { "domain": { "style": "form" }, "recordType": { "style": "form" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/DnsCheckRequest" }, "encoding": { "domain": { "style": "form" }, "recordType": { "style": "form" } } } } }, "responses": { "200": { "description": "DNS results grouped per resolver location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsCheckResponse" } } } }, "400": { "description": "Invalid or missing input fields. (Missing domain | Missing record type | Invalid record type | Invalid domain)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingDomain": { "value": { "error": "Missing domain" } }, "missingRecordType": { "value": { "error": "Missing record type" } }, "invalidRecordType": { "value": { "error": "Invalid record type" } } } } } }, "405": { "description": "Method not allowed (only POST is supported).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Method not allowed" } } } }, "429": { "description": "Too many requests (rate limit). See Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Server busy, retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "stream", "in": "query", "required": false, "description": "1 = stream results as NDJSON, one line per resolver (with an extra 'index' field).", "schema": { "type": "string", "enum": [ "1" ] } } ] } }, "/email-check": { "post": { "tags": [ "DNS Tools" ], "summary": "Validate email deliverability and related DNS configuration.", "operationId": "emailCheck", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EmailCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkimSelector": { "style": "form" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/EmailCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkimSelector": { "style": "form" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkimSelector": { "style": "form" } } } } }, "responses": { "200": { "description": "Email deliverability and configuration status for the domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckResponse" } } } }, "400": { "description": "Missing or invalid domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing domain" } } } }, "405": { "description": "Method not allowed (only POST is supported).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Method not allowed" } } } }, "429": { "description": "Too many requests (rate limit). See Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Server busy, retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/security-check": { "post": { "tags": [ "DNS Tools" ], "summary": "Run a comprehensive domain and email security check.", "operationId": "securityCheck", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SecurityCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkim_selector": { "style": "form" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SecurityCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkim_selector": { "style": "form" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/SecurityCheckRequest" }, "encoding": { "domain": { "style": "form" }, "dkim_selector": { "style": "form" } } } } }, "responses": { "200": { "description": "Security score, issues, warnings, and detailed DNS/SSL results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityCheckResponse" } } } }, "400": { "description": "Invalid domain or invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid domain format" } } } }, "405": { "description": "Method not allowed (only POST is supported).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Method not allowed" } } } }, "429": { "description": "Too many requests (rate limit). See Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Server busy, retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/spam-check": { "post": { "tags": [ "DNS Tools" ], "summary": "Check if an IP or domain is listed on common DNSBL spam lists.", "operationId": "spamCheck", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SpamCheckRequest" }, "encoding": { "target": { "style": "form" }, "mode": { "style": "form" } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SpamCheckRequest" }, "encoding": { "target": { "style": "form" }, "mode": { "style": "form" } } }, "application/json": { "schema": { "$ref": "#/components/schemas/SpamCheckRequest" }, "encoding": { "target": { "style": "form" }, "mode": { "style": "form" } } } } }, "responses": { "200": { "description": "Spam/DNSBL status for the given IP or domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpamCheckResponse" } } } }, "400": { "description": "Missing or invalid input (IP/domain).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missingTarget": { "value": { "error": "Missing IP address or domain" } }, "invalidIp": { "value": { "error": "Invalid IP address" } }, "invalidDomain": { "value": { "error": "Invalid domain" } }, "neither": { "value": { "error": "Input is neither a valid IP nor a valid domain" } } } } } }, "405": { "description": "Method not allowed (only POST is supported).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Method not allowed" } } } }, "429": { "description": "Too many requests (rate limit). See Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "Server busy, retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/ip-info": { "post": { "summary": "IP info: hostname, ASN, network and location", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "IP address, domain or 'self'" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "IP address, domain or 'self'" } } } }, "application/json": { "schema": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string", "description": "IP address, domain or 'self'" } } } } } }, "responses": { "200": { "description": "IP information", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "type": { "type": "string", "enum": [ "ip", "domain" ] }, "results": { "type": "array", "items": { "type": "object" } }, "source": { "type": "string" } } } } } }, "400": { "description": "Invalid input" }, "429": { "description": "Too many requests" }, "503": { "description": "Server busy" }, "405": { "description": "Method not allowed" } } } }, "/resolvers": { "get": { "summary": "Active resolvers and their health", "responses": { "200": { "description": "Active resolvers and health", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "standby": { "type": "integer" }, "recent_replacements": { "type": "array", "items": { "type": "object" } }, "resolvers": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "provider": { "type": "string" }, "location": { "type": "string" }, "location_nl": { "type": "string" }, "up": { "type": "boolean" } } } } } } } } } } } } }, "components": { "schemas": { "DnsCheckRequest": { "type": "object", "required": [ "domain", "recordType" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "recordType": { "type": "string", "enum": [ "A", "AAAA", "MX", "NS", "PTR", "CNAME", "SOA", "TXT", "SRV", "NAPTR", "CAA", "DS", "DNSKEY" ], "example": "MX" } } }, "DnsResultItem": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "ip": { "type": "string", "nullable": true }, "ipv6": { "type": "string", "nullable": true }, "target": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true }, "hostmaster": { "type": "string", "nullable": true }, "txt": { "type": "string", "nullable": true }, "flags": { "type": "integer", "nullable": true }, "tag": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true }, "order": { "type": "integer", "nullable": true }, "preference": { "type": "integer", "nullable": true }, "service": { "type": "string", "nullable": true }, "regexp": { "type": "string", "nullable": true }, "replacement": { "type": "string", "nullable": true }, "port": { "type": "integer", "nullable": true }, "message": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "primary_name_server": { "type": "string", "description": "SOA primary name server" }, "serial": { "type": "integer", "description": "SOA serial" }, "refresh": { "type": "integer", "description": "SOA refresh" }, "retry": { "type": "integer", "description": "SOA retry" }, "expire": { "type": "integer", "description": "SOA expire" }, "minimum_ttl": { "type": "integer", "description": "SOA minimum TTL" }, "ns_server": { "type": "string", "description": "NS target" }, "cname": { "type": "string", "description": "CNAME target" }, "ptr": { "type": "string", "description": "PTR hostname" }, "weight": { "type": "integer", "description": "SRV weight" }, "key_tag": { "type": "string", "description": "DS key tag" }, "algorithm": { "type": "string", "description": "DS/DNSKEY algorithm" }, "digest_type": { "type": "string", "description": "DS digest type" }, "digest": { "type": "string", "description": "DS digest" }, "protocol": { "type": "string", "description": "DNSKEY protocol" }, "public_key": { "type": "string", "description": "DNSKEY public key" } } }, "DnsCheckLocationResult": { "type": "object", "properties": { "location": { "type": "string" }, "ip": { "type": "string" }, "provider": { "type": "string" }, "dns_results": { "type": "array", "items": { "$ref": "#/components/schemas/DnsResultItem" } }, "resolved": { "type": "boolean" }, "location_nl": { "type": "string", "description": "Location in Dutch" }, "status": { "type": "string", "enum": [ "ok", "nodata", "nxdomain", "timeout", "servfail", "refused", "formerr", "notimp", "error", "down" ] }, "rtt_ms": { "type": "integer", "nullable": true, "description": "Resolver response time; null on cache hit" }, "cached": { "type": "boolean" } } }, "DnsCheckResponse": { "type": "array", "items": { "$ref": "#/components/schemas/DnsCheckLocationResult" } }, "EmailCheckRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "dkimSelector": { "type": "string", "example": "default" } } }, "EmailCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "mxValid": { "type": "boolean" }, "disposable": { "type": "boolean" }, "deliverable": { "type": "boolean" }, "spf": { "type": "string" }, "dmarc": { "type": "string" }, "dkim": { "type": "string" }, "mx": { "type": "string" }, "ptr": { "type": "string" }, "bimi": { "type": "string" }, "google_verification": { "type": "string" }, "null_mx": { "type": "boolean" }, "dkim_selector": { "type": "string", "description": "Selector where DKIM was found" } } }, "SecurityCheckRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "dkim_selector": { "type": "string", "example": "default" } } }, "SecurityDetailRecord": { "type": "object", "additionalProperties": true, "properties": { "value": { "type": "string" }, "mode": { "type": "string" }, "found_on": { "type": "string" }, "policy": { "type": "string" }, "subdomain_policy": { "type": "string" }, "rua": { "type": "string" }, "ruf": { "type": "string" }, "selector_used": { "type": "string" }, "status": { "type": "string" }, "applies_to": { "type": "string" }, "ds": { "type": "array", "items": { "type": "object" } }, "dnskey": { "type": "array", "items": { "type": "object" } } } }, "SslDetail": { "type": "object", "additionalProperties": true, "properties": { "issuer": { "type": "string" }, "expiry_days": { "type": "number" }, "subject": { "type": "object", "additionalProperties": { "type": "string" } }, "altnames": { "type": "array", "items": { "type": "string" } } } }, "SecurityCheckDetails": { "type": "object", "additionalProperties": true, "properties": { "input_domain": { "type": "string" }, "parent_domain": { "type": "string" }, "using_parent_fallback": { "type": "boolean" }, "SPF": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "DMARC": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "DKIM": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "BIMI": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "SSL": { "$ref": "#/components/schemas/SslDetail" }, "HSTS": { "type": "string" }, "DNSSEC": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "CAA": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "MTA_STS": { "$ref": "#/components/schemas/SecurityDetailRecord" }, "TLS_RPT": { "$ref": "#/components/schemas/SecurityDetailRecord" } } }, "SecurityCheckResponse": { "type": "object", "properties": { "percentage": { "type": "integer" }, "level": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "issues": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "improvements": { "type": "array", "items": { "type": "string" } }, "details": { "$ref": "#/components/schemas/SecurityCheckDetails" } } }, "SpamCheckRequest": { "type": "object", "required": [ "target" ], "properties": { "target": { "type": "string" }, "mode": { "type": "string", "enum": [ "auto", "ip", "domain" ], "default": "auto" } } }, "SpamDnsblResult": { "type": "object", "properties": { "name": { "type": "string" }, "host": { "type": "string" }, "listed": { "type": "boolean" }, "response": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "list_url": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "listed", "unavailable", "error" ] } } }, "SpamCheckResponse": { "type": "object", "properties": { "checked_value": { "type": "string" }, "type": { "type": "string", "enum": [ "ip", "domain" ] }, "ip": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "total_lists": { "type": "integer" }, "listed_count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SpamDnsblResult" } } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } } } } }