{ "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": "web", "description": "Web security checks and generators" }, { "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/nis2": { "get": { "tags": [ "scan" ], "summary": "NIS2 quickscan", "description": "Compute a NIS2 readiness indicator from the DNS and email layer. Maps the quickscan evidence onto NIS2 Article 21.2 measures (a–j) and returns a weighted 0-100 score, per-measure status, evidence rows, critical gaps, and fix suggestions. Evidence that is not applicable for a given domain (e.g. DNSSEC on a TLD that does not support it) is excluded from the measure's score and reduces the measure's effective weight in the total. The result is a readiness indicator only — full NIS2 compliance also requires audit of web applications, supply chain, organisational processes, and training.", "operationId": "nis2Quickscan", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain name to scan (e.g., example.com).", "schema": { "type": "string", "example": "example.com" } }, { "name": "lang", "in": "query", "required": false, "description": "Language for the standard caveat text. Defaults to English.", "schema": { "type": "string", "enum": ["en", "nl"], "example": "en" } } ], "responses": { "200": { "description": "NIS2 scorecard returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "total": { "type": "integer", "minimum": 0, "maximum": 100 }, "status": { "type": "string", "enum": ["compliant", "partial", "non-compliant", "unscannable"] }, "measures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"] }, "label": { "type": "string" }, "description": { "type": "string" }, "weight": { "type": "integer" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "status": { "type": "string", "enum": ["pass", "warning", "fail", "not-applicable"] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "checkId": { "type": "string" }, "label": { "type": "string" }, "result": { "type": "string", "enum": ["pass", "fail", "missing", "not-applicable"] }, "detail": { "type": "string" } } } }, "fixes": { "type": "array", "items": { "type": "string" } } } } }, "criticalGaps": { "type": "array", "items": { "type": "string", "enum": ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"] } }, "caveat": { "type": "string" } } } } } }, "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/Microsoft 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" } } } } } } }, "/security-headers/analyze": { "get": { "tags": [ "web" ], "summary": "Analyze live HTTP security headers", "description": "Fetch a domain's live HTTP security headers (Strict-Transport-Security, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), report per-header pass/missing status, and return the recommended baseline config with ready-to-paste fixes. If the header fetch times out, every status is reported as 'unknown' instead of 'missing'.", "operationId": "analyzeSecurityHeaders", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check", "schema": { "type": "string", "example": "example.com" } } ], "responses": { "200": { "description": "Security headers analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityHeadersAnalyzeResult" } } } }, "400": { "description": "Invalid or missing domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/security-headers/generate": { "post": { "tags": [ "web" ], "summary": "Generate HTTP security headers", "description": "Generate HTTP security headers (HSTS, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP/COEP/CORP) from a named preset or a full config. Returns the header list plus ready-to-paste outputs for Nginx, Apache, Caddy, Cloudflare, _headers files, and raw header lines. Pure compute — no network calls.", "operationId": "generateSecurityHeaders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityHeadersGenerateRequest" } } } }, "responses": { "200": { "description": "Security headers generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityHeadersGenerateResult" } } } }, "400": { "description": "Invalid body — provide a preset or a config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/csp/scan": { "post": { "tags": [ "web" ], "summary": "Scan a website's Content-Security-Policy", "description": "Crawl up to 20 same-origin pages (45s total budget), analyze the current Content-Security-Policy (enforce header, Report-Only header, or meta tag), detect weaknesses such as unsafe-inline, wildcard sources, and missing object-src/base-uri/frame-ancestors, inventory every external resource origin per directive, and synthesize a ready-to-deploy starter policy (enforce + Report-Only variants). Expensive endpoint: limited to 3 scans per 10 minutes per IP; results are cached per origin for 10 minutes so repeat scans are instant. A scan typically takes 30-45 seconds.", "operationId": "scanCsp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CspScanRequest" } } } }, "responses": { "200": { "description": "CSP scan completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CspScanResult" } } } }, "400": { "description": "Invalid body or URL that cannot be scanned (IP literals, localhost, non-https, internal hostnames)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded — 3 scans per 10 minutes per IP; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Inconclusive — no page could be crawled, so no findings or policy are reported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CspScanInconclusive" } } } } } } }, "/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 (legacy GET compatibility)", "description": "Backward-compatible GET variant for existing browser, MCP, and agent clients. New integrations should use POST. Successful responses include Deprecation and Link headers pointing to the canonical POST operation.", "operationId": "createReportSnapshotLegacyGet", "deprecated": true, "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": "Canonical method for creating 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" } } } } } } }, "/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" }, "retentionPolicy": { "type": "string", "enum": [ "indefinite" ], "description": "Stored snapshots have no automatic expiry." }, "retentionNotice": { "type": "string", "description": "Operational exceptions to the snapshot retention policy." } } } } }, "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" } } } } } }, "SecurityHeadersGenerateRequest": { "type": "object", "description": "Provide either a named preset or a full config. If both are present, config wins and preset is ignored.", "properties": { "preset": { "type": "string", "enum": [ "recommended", "strict", "report-only" ], "description": "Named baseline configuration", "example": "recommended" }, "config": { "type": "object", "description": "Full security-headers config with hsts, csp, frameOptions, contentTypeOptions, referrerPolicy, permissionsPolicy, coop, coep, and corp fields" } } }, "SecurityHeadersGenerateResult": { "type": "object", "properties": { "headers": { "type": "array", "description": "Ordered list of enabled headers", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Strict-Transport-Security" }, "value": { "type": "string", "example": "max-age=31536000; includeSubDomains" } } } }, "outputs": { "type": "object", "description": "Ready-to-paste configuration per server format", "properties": { "nginx": { "type": "string" }, "apache": { "type": "string" }, "caddy": { "type": "string" }, "cloudflare": { "type": "string" }, "headers": { "type": "string", "description": "Netlify/Vercel-style _headers file" }, "raw": { "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "SecurityHeadersAnalyzeResult": { "type": "object", "properties": { "domain": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "httpsAvailable": { "type": "boolean" }, "headerFetchTimedOut": { "type": "boolean", "description": "When true, header absence could not be verified — every status is 'unknown' and a note is set" }, "note": { "type": "string", "description": "Present only when the header fetch timed out" }, "current": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Content-Security-Policy" }, "present": { "type": "boolean" }, "value": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pass", "missing", "unknown" ] } } } }, "missing": { "type": "array", "description": "Header names confidently missing (empty when the fetch timed out)", "items": { "type": "string" } }, "recommended": { "type": "object", "description": "The recommended baseline security-headers config" }, "outputs": { "type": "object", "description": "Ready-to-paste recommended configuration per server format" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "CspScanRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Site to scan. A bare hostname is treated as https://", "example": "https://example.com" }, "strict": { "type": "boolean", "description": "Synthesize a stricter policy", "default": false } } }, "CspScanResult": { "type": "object", "properties": { "url": { "type": "string", "description": "Normalized start URL of the crawl" }, "origin": { "type": "string", "example": "https://example.com" }, "pagesCrawled": { "type": "integer", "description": "Number of same-origin pages successfully crawled (max 20)" }, "pagesFailed": { "type": "integer" }, "truncated": { "type": "boolean", "description": "True when more pages were discovered than the crawl budget allowed" }, "currentCsp": { "type": "object", "description": "The policy currently deployed, if any", "properties": { "source": { "type": "string", "enum": [ "header", "report-only", "meta" ], "nullable": true, "description": "Where the policy was found; null when the site has no CSP" }, "policy": { "type": "string", "nullable": true } } }, "findings": { "type": "array", "description": "Weaknesses detected in the current policy (or the absence of one)", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "info" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "directive": { "type": "string", "example": "script-src" } } } }, "inventory": { "type": "array", "description": "Observed resource origins grouped by CSP directive ('self' first, externals sorted)", "items": { "type": "object", "properties": { "directive": { "type": "string", "example": "script-src" }, "origins": { "type": "array", "items": { "type": "string" } } } } }, "inlineScripts": { "type": "integer", "description": "Total inline script blocks across crawled pages" }, "inlineStyles": { "type": "integer" }, "eventHandlerAttrs": { "type": "integer", "description": "Total inline event-handler attributes (onclick, onload, ...)" }, "synthesis": { "type": "object", "description": "Generated starter policy built from observed resources", "properties": { "policyString": { "type": "string", "description": "Ready-to-deploy Content-Security-Policy value" }, "reportOnlyString": { "type": "string", "description": "Content-Security-Policy-Report-Only value for safe rollout" }, "notes": { "type": "array", "items": { "type": "string" } } } } } }, "CspScanInconclusive": { "type": "object", "description": "Returned with HTTP 502 when zero pages could be crawled — the scan is inconclusive, never a confident negative", "properties": { "error": { "type": "string", "example": "Could not reach the site" }, "inconclusive": { "type": "boolean", "example": true }, "pagesFailed": { "type": "integer" } } }, "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." } }