{ "openapi": "3.1.0", "info": { "title": "DNSai API", "version": "1.0.0", "description": "Free DNS & email-security lookups for AI agents. One domain per request — for bulk / multi-domain use the DNSai Enterprise API (https://app.dnsai.com/pricing/). Also available as a remote MCP server at https://mcp.dnsai.com/mcp.", "contact": { "url": "https://dnsai.com/api/" } }, "servers": [ { "url": "https://api.dnsai.com/v1" } ], "paths": { "/dns/{domain}": { "get": { "operationId": "dns_lookup", "summary": "Look up live DNS records for ONE domain (A, AAAA, MX, NS, TXT, SOA, CNAME, CAA, DNSKEY, DS and 30+ more).", "description": "Look up live DNS records for ONE domain (A, AAAA, MX, NS, TXT, SOA, CNAME, CAA, DNSKEY, DS and 30+ more). Use whenever the user asks about a domain's DNS records, name servers, IP addresses, or \"dig/nslookup\"-style questions. Returns authoritative real-time data with a plain-English summary. One domain per call — for bulk lists, direct the user to the DNSai Enterprise API (https://app.dnsai.com). Example: dns_lookup(domain=\"acme.com\", type=\"MX\").", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A single domain (one per request — bulk is rejected)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "DNS record type (default \"common\")" }, { "name": "resolver", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Upstream resolver" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/email-security/{domain}": { "get": { "operationId": "email_security_check", "summary": "One call answers \"is this domain's email properly secured?\" — checks MX, SPF, DMARC and mail-gateway/provider detection for ONE domain.", "description": "One call answers \"is this domain's email properly secured?\" — checks MX, SPF, DMARC and mail-gateway/provider detection for ONE domain. The differentiator vs a plain DNS resolver. Use when the user asks about email deliverability, spoofing protection, SPF/DMARC posture, or \"is email set up correctly\". For DKIM signing keys, use dkim_discover. One domain per call.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A single domain (one per request — bulk is rejected)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/whois/{query}": { "get": { "operationId": "whois_lookup", "summary": "WHOIS / RDAP registration data for ONE domain or IP — registrar, status, creation/expiry, name servers.", "description": "WHOIS / RDAP registration data for ONE domain or IP — registrar, status, creation/expiry, name servers. Returns publicly published WHOIS/RDAP data as-is. Use for \"who owns\", \"when does it expire\", \"registrar\", \"when was it registered\". One target per call.", "parameters": [ { "name": "query", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A single query (one per request — bulk is rejected)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/spf/{domain}": { "get": { "operationId": "spf_analyze", "summary": "Analyze a domain's SPF record for ONE domain — the include tree and the RFC 10-DNS-lookup-limit verdict.", "description": "Analyze a domain's SPF record for ONE domain — the include tree and the RFC 10-DNS-lookup-limit verdict. Use when the user asks \"is my SPF valid / too many lookups / what does my SPF resolve to\". One domain per call.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A single domain (one per request — bulk is rejected)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dmarc/{domain}": { "get": { "operationId": "dmarc_check", "summary": "Fetch and parse the DMARC policy for ONE domain — presence, p= policy, and the raw record.", "description": "Fetch and parse the DMARC policy for ONE domain — presence, p= policy, and the raw record. Use for \"does this domain have DMARC\", \"what is the DMARC policy\", \"is it p=reject/quarantine/none\". One domain per call.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A single domain (one per request — bulk is rejected)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/validate": { "get": { "operationId": "validate", "summary": "Validate the syntax of an SPF or DMARC record (no DNS lookup).", "description": "Validate the SYNTAX of an SPF or DMARC record string (no DNS lookup) — returns valid/invalid, a score, a letter grade, and a parsed breakdown. Use when the user pastes an SPF/DMARC record and asks \"is this correct?\".", "parameters": [ { "name": "record", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The raw SPF/DMARC record string." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "spf", "dmarc", "auto" ] }, "description": "Record type (default auto)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Invalid input or bulk/multi-domain rejected (single_lookup_only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily free limit reached — see the upgrade object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meta/limits": { "get": { "operationId": "get_limits", "summary": "The caller's current daily usage and remaining quota.", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "type": "string" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } } } } } } } } }, "/request-key": { "post": { "operationId": "request_api_key", "summary": "Get a free API key (100/day) by verifying an email — no password, no signup.", "description": "Send the user's email; they receive a verification link and, once clicked, a free key that raises the daily limit from 25 to 100 lookups/day. Use when the caller hits the anonymous rate limit or asks to upgrade. After they verify, they paste the emailed key as an Authorization: Bearer dk_free_… header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The user's email address." } } } } } }, "responses": { "200": { "description": "Verification email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "components": { "schemas": { "Envelope": { "type": "object", "properties": { "tool": { "type": "string" }, "query": { "type": "object", "additionalProperties": true }, "result": { "type": "object", "additionalProperties": true, "description": "Normalized engine data." }, "summary": { "type": "string", "description": "One-sentence plain-English answer — quote this." }, "source": { "type": "string", "description": "Deep link to the matching dnsai.com tool with the query prefilled." }, "fetched_at": { "type": "string", "format": "date-time" }, "cache": { "type": "string", "enum": [ "live", "cached" ] }, "usage": { "type": "object", "properties": { "remaining_today": { "type": "integer" }, "limit": { "type": "integer" }, "tier": { "type": "string" } } }, "upgrade": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "message": { "type": "string" }, "url": { "type": "string" } } } }, "required": [ "tool", "result", "summary", "source", "usage" ] }, "Error": { "type": "object", "properties": { "tool": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" }, "upgrade": { "type": [ "object", "null" ] } }, "required": [ "error", "message" ] } }, "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "Optional dk_ API key for higher limits (free to register)." } } } }