{ "openapi": "3.0.3", "info": { "title": "IntoDNS.AI API", "description": "Public DNS security and email deliverability analysis API. Analyze SPF, DKIM, DMARC, DNSSEC, MTA-STS, BIMI, SMTP STARTTLS, FCrDNS, blacklists, and more with deterministic results and optional AI explanations.", "version": "2.0.0", "contact": { "name": "IntoDNS.AI Support", "url": "https://intodns.ai", "email": "support@cobytes.com" }, "license": { "name": "Proprietary", "url": "https://intodns.ai/terms" } }, "servers": [ { "url": "https://intodns.ai/api", "description": "Production server" } ], "tags": [ { "name": "scan", "description": "Domain scanning operations" }, { "name": "dns", "description": "DNS lookup and validation" }, { "name": "email", "description": "Email security checks" }, { "name": "ai", "description": "AI-assisted explanations and fixes" } ], "paths": { "/scan/quick": { "get": { "tags": [ "scan" ], "summary": "Quick domain scan", "description": "Perform a fast security overview of a domain covering DNS, email, and basic security checks.", "operationId": "quickScan", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain name to scan (e.g., example.com)", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Scan completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickScanResult" } } } }, "400": { "description": "Invalid domain name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/scan/deep": { "post": { "tags": [ "scan" ], "summary": "Deep security scan", "description": "Comprehensive security analysis using Internet.nl infrastructure. This is an asynchronous operation.", "operationId": "deepScan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepScanRequest" } } } }, "responses": { "200": { "description": "Scan started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepScanResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dns/lookup": { "get": { "tags": [ "dns" ], "summary": "DNS record lookup", "description": "Query DNS records for a domain. Supports all major record types.", "operationId": "dnsLookup", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain name to query", "schema": { "type": "string", "example": "example.com" } }, { "name": "type", "in": "query", "required": false, "description": "DNS record type (default: all)", "schema": { "type": "string", "enum": [ "A", "AAAA", "MX", "TXT", "NS", "SOA", "CAA", "CNAME", "PTR" ], "example": "A" } } ], "responses": { "200": { "description": "DNS records retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSLookupResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dns/dnssec": { "get": { "tags": [ "dns" ], "summary": "DNSSEC validation", "description": "Validate DNSSEC chain of trust for a domain.", "operationId": "dnssecValidation", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to validate", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "DNSSEC validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSSECResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dns/propagation": { "get": { "tags": [ "dns" ], "summary": "DNS propagation check", "description": "Check DNS propagation across global nameservers.", "operationId": "dnsPropagation", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } }, { "name": "type", "in": "query", "required": false, "description": "Record type (default: A)", "schema": { "type": "string", "enum": [ "A", "AAAA", "MX", "TXT" ], "example": "A" } } ], "responses": { "200": { "description": "Propagation check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropagationResult" } } } } } } }, "/email/check": { "get": { "tags": [ "email" ], "summary": "Email security check", "description": "Comprehensive email authentication and deliverability analysis including SPF, DKIM, DMARC.", "operationId": "emailCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to analyze", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Email security analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email/spf": { "get": { "tags": [ "email" ], "summary": "SPF record check", "description": "Analyze SPF (Sender Policy Framework) record for a domain.", "operationId": "spfCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "SPF analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SPFResult" } } } } } } }, "/email/dkim": { "get": { "tags": [ "email" ], "summary": "DKIM discovery", "description": "Discover and validate DKIM keys for a domain.", "operationId": "dkimDiscovery", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "DKIM discovery result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DKIMResult" } } } } } } }, "/email/dmarc": { "get": { "tags": [ "email" ], "summary": "DMARC policy check", "description": "Analyze DMARC policy for a domain.", "operationId": "dmarcCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "DMARC analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DMARCResult" } } } } } } }, "/email/bimi": { "get": { "tags": [ "email" ], "summary": "BIMI record, logo, and mark-certificate check", "description": "Analyze BIMI record syntax, hosted SVG logo reachability, and optional VMC/CMC authority certificate URL.", "operationId": "bimiCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "BIMI analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BIMIResult" } } } } } } }, "/email/mta-sts": { "get": { "tags": [ "email" ], "summary": "MTA-STS policy check", "description": "Check the _mta-sts TXT record and fetch the HTTPS MTA-STS policy file.", "operationId": "mtaStsCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "MTA-STS analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MTASTSResult" } } } } } } }, "/email/smtp-tls": { "get": { "tags": [ "email" ], "summary": "SMTP STARTTLS and certificate check", "description": "Connect to MX servers on SMTP port 25, verify STARTTLS support, TLS certificate trust, hostname match, expiry, and FCrDNS.", "operationId": "smtpTlsCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "SMTP STARTTLS analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SMTPTLSResult" } } } } } } }, "/email/fcrdns": { "get": { "tags": [ "email" ], "summary": "FCrDNS / PTR check", "description": "Check PTR records and forward-confirmed reverse DNS for mail-server IPs.", "operationId": "fcrdnsCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "FCrDNS analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FCrDNSResult" } } } } } } }, "/email/blacklist": { "get": { "tags": [ "email" ], "summary": "Mail-server blacklist check", "description": "Check domain mail-server IPs against common DNSBL blocklists.", "operationId": "blacklistCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Blacklist analysis result", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/email/sender-requirements": { "get": { "tags": [ "email" ], "summary": "Google/Yahoo sender requirements check", "description": "Check SPF, DKIM, DMARC, FCrDNS, and other mailbox-provider sender requirements.", "operationId": "senderRequirementsCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Sender requirements result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRequirementsResult" } } } } } } }, "/dns/tlsa": { "get": { "tags": [ "dns" ], "summary": "DANE/TLSA check", "description": "Check SMTP DANE/TLSA records for domain MX hosts.", "operationId": "tlsaCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "DANE/TLSA result", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/report/everything": { "get": { "tags": [ "scan" ], "summary": "Everything report", "description": "Generate a bookmarkable full DNS and email security report as JSON or Markdown. Includes quick scan, DNS records, DNSSEC, SPF lookup graph, DKIM, DMARC, BIMI logo/certificate checks, MTA-STS, SMTP STARTTLS, FCrDNS, blacklists, sender requirements, and web security signals.", "operationId": "everythingReport", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to report on", "schema": { "type": "string", "example": "example.com" } }, { "name": "format", "in": "query", "required": false, "description": "Response format", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Everything report generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EverythingReport" } }, "text/markdown": { "schema": { "type": "string" } } } } } } }, "/report/snapshot": { "get": { "tags": [ "scan" ], "summary": "Create Everything report snapshot", "description": "Create a free fixed Everything Report evidence snapshot with timestamp, content hash, and stable JSON/Markdown retrieval URL. No signup or API key is required; generous abuse protection may return HTTP 429 with Retry-After.", "operationId": "createReportSnapshot", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to snapshot", "schema": { "type": "string", "example": "example.com" } }, { "name": "format", "in": "query", "required": false, "description": "Response format", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "201": { "description": "Report snapshot created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EverythingReport" } }, "text/markdown": { "schema": { "type": "string" } } } } } }, "post": { "tags": [ "scan" ], "summary": "Create Everything report snapshot", "description": "POST variant of the free report snapshot creator. Query parameters are the same as GET; no signup or API key is required; generous abuse protection may return HTTP 429 with Retry-After.", "operationId": "postCreateReportSnapshot", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to snapshot", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "201": { "description": "Report snapshot created" } } } }, "/report/snapshot/{snapshotId}": { "get": { "tags": [ "scan" ], "summary": "Read Everything report snapshot", "description": "Retrieve a previously created free fixed Everything Report evidence snapshot.", "operationId": "readReportSnapshot", "parameters": [ { "name": "snapshotId", "in": "path", "required": true, "description": "Snapshot identifier returned by /report/snapshot", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Response format", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Report snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EverythingReport" } }, "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Snapshot not found" } } } }, "/ai/explain": { "post": { "tags": [ "ai" ], "summary": "AI explanation", "description": "Get an AI-assisted explanation for DNS or email security issues.", "operationId": "aiExplain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIExplainRequest" } } } }, "responses": { "200": { "description": "AI explanation generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIExplainResponse" } } } } } } }, "/ai/fix": { "post": { "tags": [ "ai" ], "summary": "AI fix suggestion", "description": "Get AI-assisted fix recommendations with configuration examples.", "operationId": "aiFix", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIFixRequest" } } } }, "responses": { "200": { "description": "Fix suggestion generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIFixResponse" } } } } } } }, "/health": { "get": { "tags": [ "system" ], "summary": "Health check", "description": "Check API health status.", "operationId": "healthCheck", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } } }, "components": { "schemas": { "QuickScanResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "categories": { "type": "object", "properties": { "dns": { "$ref": "#/components/schemas/CategoryScore" }, "email": { "$ref": "#/components/schemas/CategoryScore" }, "security": { "$ref": "#/components/schemas/CategoryScore" } } }, "critical_issues": { "type": "integer" }, "warnings": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } }, "CategoryScore": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "issues": { "type": "integer" } } }, "DeepScanRequest": { "type": "object", "required": [ "domain", "type" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "type": { "type": "string", "enum": [ "web", "mail" ], "example": "web" } } }, "DeepScanResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "scan_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "estimated_time": { "type": "integer", "description": "Estimated completion time in seconds" } } }, "DNSLookupResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "records": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "cached": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } } }, "DNSSECResult": { "type": "object", "properties": { "domain": { "type": "string" }, "signed": { "type": "boolean", "description": "Whether the domain has DNSKEY records (DNSSEC enabled)" }, "valid": { "type": "boolean", "description": "Whether DNSSEC validation passes (AD flag set by resolver)" }, "chain": { "type": "array", "description": "DNSKEY and DS records forming the chain of trust", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "algorithm": { "type": "integer" }, "digestType": { "type": "integer", "description": "0 for DNSKEY, 1=SHA-1, 2=SHA-256, 4=SHA-384 for DS" }, "digest": { "type": "string" }, "flags": { "type": "integer", "description": "DNSKEY flags (256=ZSK, 257=KSK)" }, "protocol": { "type": "integer" }, "publicKey": { "type": "string" } } } }, "nsec3param": { "type": "object", "description": "NSEC3 parameter check results", "properties": { "exists": { "type": "boolean" }, "hashAlgorithm": { "type": "integer" }, "flags": { "type": "integer" }, "iterations": { "type": "integer" }, "salt": { "type": "string" }, "rfc9276Compliant": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object" } } } }, "rrsig": { "type": "object", "description": "RRSIG signature check results", "properties": { "exists": { "type": "boolean" }, "records": { "type": "array", "items": { "type": "object", "properties": { "typeCovered": { "type": "string" }, "algorithm": { "type": "integer" }, "originalTTL": { "type": "integer" }, "daysUntilExpiry": { "type": "integer" }, "isExpired": { "type": "boolean" } } } }, "algorithmSecurity": { "type": "string", "enum": [ "modern", "acceptable", "deprecated", "insecure", "unknown" ] }, "issues": { "type": "array", "items": { "type": "object" } } } }, "errors": { "type": "array", "items": { "type": "string" } } } }, "PropagationResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "type": { "type": "string" }, "propagated": { "type": "boolean" }, "servers_checked": { "type": "integer" }, "servers_matching": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "server": { "type": "string" }, "location": { "type": "string" }, "value": { "type": "array", "items": { "type": "string" } }, "response_time": { "type": "integer" } } } } } }, "EmailCheckResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "domain": { "type": "string" }, "spf": { "$ref": "#/components/schemas/SPFResult" }, "dkim": { "$ref": "#/components/schemas/DKIMResult" }, "dmarc": { "$ref": "#/components/schemas/DMARCResult" }, "mx": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "priority": { "type": "integer" }, "host": { "type": "string" } } } } } }, "score": { "type": "integer" } } }, "SPFResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "record": { "type": "string" }, "valid": { "type": "boolean" }, "mechanisms": { "type": "array", "items": { "type": "string" } }, "lookups": { "type": "integer" }, "lookupGraph": { "type": "object", "description": "Recursive SPF include/redirect lookup graph" }, "flattened": { "type": "object", "description": "Generated flattened SPF record and warnings" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "BIMIResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "record": { "type": "string" }, "valid": { "type": "boolean" }, "logoUrl": { "type": "string" }, "authorityUrl": { "type": "string" }, "logo": { "type": "object", "description": "Hosted SVG reachability, content type, and size checks" }, "authority": { "type": "object", "description": "VMC/CMC mark-certificate reachability and parse result" }, "issues": { "type": "array", "items": { "type": "string" } } } }, "MTASTSResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "record": { "type": "string" }, "policyId": { "type": "string" }, "policy": { "type": "object" }, "policyUrl": { "type": "string" }, "valid": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "string" } } } }, "SMTPTLSResult": { "type": "object", "properties": { "domain": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" }, "mxRecords": { "type": "array", "items": { "type": "object" } }, "servers": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object" }, "issues": { "type": "array", "items": { "type": "string" } } } }, "FCrDNSResult": { "type": "object", "properties": { "domain": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "check": { "type": "string", "example": "fcrdns" }, "description": { "type": "string" }, "result": { "type": "object", "properties": { "checked": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object" } }, "issues": { "type": "array", "items": { "type": "string" } } } }, "citationUrl": { "type": "string" }, "apiUrl": { "type": "string" } } }, "SenderRequirementsResult": { "type": "object", "properties": { "domain": { "type": "string" }, "overallStatus": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object" } } }, "EverythingReport": { "type": "object", "properties": { "domain": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "reportUrl": { "type": "string" }, "summary": { "type": "object" }, "sections": { "type": "object" }, "citations": { "type": "array", "items": { "type": "object" } }, "machineReadable": { "type": "object" }, "evidence": { "type": "object", "properties": { "liveReportUrl": { "type": "string" }, "snapshotCreateUrl": { "type": "string" }, "snapshotUrl": { "type": "string" }, "snapshotMarkdownUrl": { "type": "string" }, "snapshotId": { "type": "string" }, "contentHash": { "type": "string" }, "formatVersion": { "type": "string" } } } } }, "DKIMResult": { "type": "object", "properties": { "selectors_found": { "type": "array", "items": { "type": "string" } }, "valid_keys": { "type": "integer" } } }, "DMARCResult": { "type": "object", "properties": { "exists": { "type": "boolean" }, "policy": { "type": "string", "enum": [ "none", "quarantine", "reject" ] }, "pct": { "type": "integer" }, "rua": { "type": "array", "items": { "type": "string" } } } }, "AIExplainRequest": { "type": "object", "required": [ "issue_type" ], "properties": { "issue_type": { "type": "string", "example": "spf_too_many_lookups" }, "context": { "type": "object", "example": { "domain": "example.com", "current_lookups": 12 } } } }, "AIExplainResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "explanation": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "impact": { "type": "string" }, "recommendation": { "type": "string" } } }, "AIFixRequest": { "type": "object", "required": [ "issue", "domain" ], "properties": { "issue": { "type": "string", "example": "missing_dmarc" }, "domain": { "type": "string", "example": "example.com" }, "current_config": { "type": "object" } } }, "AIFixResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "fix": { "type": "object", "properties": { "dns_record": { "type": "string" }, "record_type": { "type": "string" }, "value": { "type": "string" }, "explanation": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } } } } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_DOMAIN" }, "message": { "type": "string", "example": "The provided domain is not valid" }, "details": { "type": "string" } } } } } }, "securitySchemes": {} }, "security": [], "x-access": { "authentication": "none", "publicEndpoints": "Public DNS, email, blacklist, quick-scan, Everything Report, and report snapshot endpoints are free and available without signup or API keys for normal diagnostic use. Generous abuse protection may return HTTP 429 with Retry-After for bursts, write-style snapshot creation, and paid AI helper endpoints.", "canonicalApiOrigin": "https://intodns.ai/api", "invalidApiOrigins": [ "https://api.intodns.io", "https://intodns.io/api-docs/v1" ], "invalidApiExamples": [ "https://api.intodns.io/v1/domain/{domain}", "https://api.intodns.io/v1/domain/example.com" ], "llmDiscovery": "LLM discovery files are static and cacheable: /llms.txt, /llms-full.txt, /llms.json, /llm/api.md.", "protection": "Costly write-style or AI/raw-message endpoints may return HTTP 429 with Retry-After if abuse protection triggers." } }