{"openapi":"3.1.0","info":{"title":"DNSDeets API","version":"1.0.0","description":"Free domain security scanner: email authentication (SPF/DKIM/DMARC/MTA-STS), DNS hygiene, TLS, HTTP headers, and registration health with an explainable findings ledger. Anonymous rate limits apply per IP."},"servers":[{"url":"https://dnsdeets.com"}],"paths":{"/api/v1/scan":{"get":{"summary":"Scan a domain","description":"Full scan. Results are cached for 10 minutes.","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"example":"example.com"}],"responses":{"200":{"description":"Scan result","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"scanned_at":{"type":"string"},"domain_class":{"type":"string","enum":["email","web_only","parked"]},"score":{"type":"number","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"scoring_version":{"type":"number"},"summary":{"type":"object","properties":{"plain":{"type":"string"},"technical":{"type":"string"}},"required":["plain","technical"],"additionalProperties":false},"providers":{"type":"object","properties":{"emailProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"securityGateway":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"dnsProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"transactionalSenders":{"type":"array","items":{"type":"string"}}},"required":["emailProvider","securityGateway","dnsProvider","transactionalSenders"],"additionalProperties":false},"top_fixes":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["email","dns","tls_web","domain"]},"status":{"type":"string","enum":["pass","fail","warn","info","not_assessed"]},"severity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}]},"points":{"type":"number"},"observed":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assessed":{"type":"boolean"},"title":{"type":"string"},"plain":{"type":"string"},"technical":{"type":"string"},"fix":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["foundation","hardening","optional"]},"effort":{"type":"string","enum":["low","medium","high"]},"docs":{"type":"string"}},"required":["id","category","status","severity","points","observed","assessed","title","plain","technical","fix","tier","effort","docs"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["email","dns","tls_web","domain"]},"status":{"type":"string","enum":["pass","fail","warn","info","not_assessed"]},"severity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}]},"points":{"type":"number"},"observed":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assessed":{"type":"boolean"},"title":{"type":"string"},"plain":{"type":"string"},"technical":{"type":"string"},"fix":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["foundation","hardening","optional"]},"effort":{"type":"string","enum":["low","medium","high"]},"docs":{"type":"string"}},"required":["id","category","status","severity","points","observed","assessed","title","plain","technical","fix","tier","effort","docs"],"additionalProperties":false}},"categories":{"type":"object","propertyNames":{"type":"string","enum":["email","dns","tls_web","domain"]},"additionalProperties":{"type":"object","properties":{"possible":{"type":"number"},"lost":{"type":"number"}},"required":["possible","lost"],"additionalProperties":false}},"observed":{"type":"object","properties":{"dns":{},"email":{},"tls":{},"http":{},"rdap":{},"resolvers":{}},"required":["dns","email","tls","http","rdap","resolvers"],"additionalProperties":false},"meta":{"type":"object","properties":{"duration_ms":{"type":"number"},"cache_hit":{"type":"boolean"},"probe_used":{"type":"boolean"},"not_assessed":{"type":"array","items":{"type":"string"}}},"required":["duration_ms","cache_hit","probe_used","not_assessed"],"additionalProperties":false}},"required":["id","domain","scanned_at","domain_class","score","grade","scoring_version","summary","providers","top_fixes","findings","categories","observed","meta"],"additionalProperties":false}}}},"400":{"description":"Invalid domain"},"429":{"description":"Rate limited (Retry-After header set)"}}}},"/api/v1/scan/stream":{"get":{"summary":"Scan with progress (SSE)","description":"Server-sent events: `stage` events, then one `result` event with the same JSON as /scan.","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"example":"example.com"}],"responses":{"200":{"description":"text/event-stream"}}}},"/api/v1/scan/{id}":{"get":{"summary":"Retrieve a stored scan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stored scan","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"scanned_at":{"type":"string"},"domain_class":{"type":"string","enum":["email","web_only","parked"]},"score":{"type":"number","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"scoring_version":{"type":"number"},"summary":{"type":"object","properties":{"plain":{"type":"string"},"technical":{"type":"string"}},"required":["plain","technical"],"additionalProperties":false},"providers":{"type":"object","properties":{"emailProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"securityGateway":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"dnsProvider":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"confidence":{"type":"string","enum":["high","medium"]},"via":{"type":"string"}},"required":["name","confidence","via"],"additionalProperties":false},{"type":"null"}]},"transactionalSenders":{"type":"array","items":{"type":"string"}}},"required":["emailProvider","securityGateway","dnsProvider","transactionalSenders"],"additionalProperties":false},"top_fixes":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["email","dns","tls_web","domain"]},"status":{"type":"string","enum":["pass","fail","warn","info","not_assessed"]},"severity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}]},"points":{"type":"number"},"observed":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assessed":{"type":"boolean"},"title":{"type":"string"},"plain":{"type":"string"},"technical":{"type":"string"},"fix":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["foundation","hardening","optional"]},"effort":{"type":"string","enum":["low","medium","high"]},"docs":{"type":"string"}},"required":["id","category","status","severity","points","observed","assessed","title","plain","technical","fix","tier","effort","docs"],"additionalProperties":false}},"findings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string","enum":["email","dns","tls_web","domain"]},"status":{"type":"string","enum":["pass","fail","warn","info","not_assessed"]},"severity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}]},"points":{"type":"number"},"observed":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"assessed":{"type":"boolean"},"title":{"type":"string"},"plain":{"type":"string"},"technical":{"type":"string"},"fix":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["foundation","hardening","optional"]},"effort":{"type":"string","enum":["low","medium","high"]},"docs":{"type":"string"}},"required":["id","category","status","severity","points","observed","assessed","title","plain","technical","fix","tier","effort","docs"],"additionalProperties":false}},"categories":{"type":"object","propertyNames":{"type":"string","enum":["email","dns","tls_web","domain"]},"additionalProperties":{"type":"object","properties":{"possible":{"type":"number"},"lost":{"type":"number"}},"required":["possible","lost"],"additionalProperties":false}},"observed":{"type":"object","properties":{"dns":{},"email":{},"tls":{},"http":{},"rdap":{},"resolvers":{}},"required":["dns","email","tls","http","rdap","resolvers"],"additionalProperties":false},"meta":{"type":"object","properties":{"duration_ms":{"type":"number"},"cache_hit":{"type":"boolean"},"probe_used":{"type":"boolean"},"not_assessed":{"type":"array","items":{"type":"string"}}},"required":["duration_ms","cache_hit","probe_used","not_assessed"],"additionalProperties":false}},"required":["id","domain","scanned_at","domain_class","score","grade","scoring_version","summary","providers","top_fixes","findings","categories","observed","meta"],"additionalProperties":false}}}},"404":{"description":"Not found or expired"}}}},"/api/v1/dkim":{"post":{"summary":"Check one DKIM selector","requestBody":{"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":255},"selector":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$"}},"required":["domain","selector"],"additionalProperties":false}}}},"responses":{"200":{"description":"Selector result"}}}},"/api/v1/checks":{"get":{"summary":"The check catalog","responses":{"200":{"description":"Catalog"}}}},"/api/v1/feedback":{"post":{"summary":"Send feedback","requestBody":{"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":5000},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"page":{"type":"string","maxLength":255}},"required":["message"],"additionalProperties":false}}}},"responses":{"200":{"description":"Delivered"}}}}}}