{ "openapi": "3.1.0", "info": { "title": "DnsGuard API", "version": "0.7.2", "summary": "Email-domain health checks: SPF, DKIM, DMARC, BIMI, MX, MTA-STS, TLS-RPT.", "description": "Free JSON API behind https://dnsguard.mike-tusa.workers.dev. No key needed for light use (about 20 checks/min per IP; anonymous users share about 5,000 checks per UTC day). A free API key (Google sign-in on the homepage) allows about 120/min and 1,000/day; DnsGuard Pro ($9/mo, https://buy.polar.sh/polar_cl_gikZjiwyAE6uZPCem4zDUlQLJTrEMo7VHvCph3xozYN) about 600/min and 10,000/day. Results are cached for 2 minutes per edge isolate; cache hits do not count. There are no X-RateLimit-* headers; a 429 carries Retry-After. AI agents can also use the remote MCP server at https://dnsguard.mike-tusa.workers.dev/mcp (see /llms.txt).", "contact": { "name": "DnsGuard", "email": "digitalpromohub.support+dnsguard@gmail.com", "url": "https://dnsguard.mike-tusa.workers.dev" } }, "servers": [ { "url": "https://dnsguard.mike-tusa.workers.dev" } ], "externalDocs": { "description": "Human-readable API docs", "url": "https://dnsguard.mike-tusa.workers.dev/#api" }, "tags": [ { "name": "checks" }, { "name": "meta" }, { "name": "mcp" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Free key (`dg_live_` + 64 hex) or DnsGuard Pro license (prefix `DNSG`). Optional." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Same keys as bearerAuth, alternative header." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Finding": { "type": "object", "required": [ "level", "message" ], "properties": { "level": { "type": "string", "enum": [ "pass", "info", "warn", "fail" ] }, "message": { "type": "string" } } }, "Check": { "type": "object", "required": [ "status", "score", "maxScore", "findings", "recommendations" ], "description": "Common fields of every check. Each check adds its own record-specific fields (e.g. spf.lookupCount, dmarc.policy, dkim.keys, mtaSts.policyFetch).", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail", "info" ] }, "score": { "type": "number" }, "maxScore": { "type": "number" }, "bonus": { "type": "boolean", "description": "true for mtaSts and tlsRpt (bonus points)" }, "notApplicable": { "type": "boolean" }, "record": { "type": [ "string", "null" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "recommendations": { "type": "array", "items": { "type": "string" } } } }, "CheckResult": { "type": "object", "required": [ "domain", "organizationalDomain", "checkedAt", "score", "maxScore", "scoreBreakdown", "grade", "notes", "checks", "meta" ], "properties": { "domain": { "type": "string", "examples": [ "example.com" ] }, "organizationalDomain": { "type": "string" }, "nonSending": { "type": "boolean", "description": "Null MX + \"v=spf1 -all\": DKIM and BIMI scored not applicable" }, "checkedAt": { "type": "string", "format": "date-time" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxScore": { "type": "integer", "const": 100 }, "scoreBreakdown": { "type": "object", "required": [ "base", "bonus", "bonusMax", "cap" ], "properties": { "base": { "type": "integer" }, "bonus": { "type": "integer" }, "bonusMax": { "type": "integer", "const": 5 }, "cap": { "type": "integer", "const": 100 } } }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "object", "required": [ "mx", "spf", "dmarc", "dkim", "bimi", "mtaSts", "tlsRpt" ], "properties": { "mx": { "$ref": "#/components/schemas/Check" }, "spf": { "$ref": "#/components/schemas/Check" }, "dmarc": { "$ref": "#/components/schemas/Check" }, "dkim": { "$ref": "#/components/schemas/Check" }, "bimi": { "$ref": "#/components/schemas/Check" }, "mtaSts": { "$ref": "#/components/schemas/Check" }, "tlsRpt": { "$ref": "#/components/schemas/Check" } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "dnsQueries": { "type": "integer" }, "resolvers": { "type": "array", "items": { "type": "string" } }, "durationMs": { "type": "integer" } } } } }, "JsonRpcMessage": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } }, "paths": { "/api/check": { "get": { "tags": [ "checks" ], "operationId": "checkDomain", "summary": "Check a domain's email authentication records", "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain to check. A URL or email address is reduced to its domain. IP addresses are rejected.", "schema": { "type": "string", "maxLength": 300 }, "example": "example.com" }, { "name": "selector", "in": "query", "required": false, "description": "Your DKIM selector (s= value). Letters, digits, \"-\", \"_\" and up to 3 dots.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,63}(\\.[A-Za-z0-9_-]{1,63}){0,3}$" } } ], "responses": { "200": { "description": "Check result", "headers": { "x-cache": { "description": "`HIT` (served from the 2-minute result cache; no quota used) or `MISS`", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] } }, "x-dnsguard-tier": { "description": "Present on keyed requests: `free` or `pro`", "schema": { "type": "string", "enum": [ "free", "pro" ] } }, "x-dnsguard-quota-remaining": { "description": "Keyed MISS responses: checks left in your daily cap (UTC day)", "schema": { "type": "integer" } }, "x-dnsguard-quota": { "description": "`unavailable` when the daily counter could not be reached (the check is still served; the per-minute limit applies)", "schema": { "type": "string", "enum": [ "unavailable" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } }, "400": { "description": "`invalid_domain` or `invalid_selector`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_api_key`: a key was sent but is unknown, revoked or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "`method_not_allowed`: use GET", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`domain_not_found`: the domain does not exist (NXDOMAIN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per-minute), `daily_quota_exceeded` (your key's daily cap) or `daily_capacity_reached` (shared free daily allowance)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "x-dnsguard-tier": { "description": "Present on keyed requests: `free` or `pro`", "schema": { "type": "string", "enum": [ "free", "pro" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`dns_unavailable`: upstream DNS-over-HTTPS resolvers failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`storage_unavailable` (Retry-After: 3600), `keys_unavailable` or `free_api_disabled`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "`timeout`: the check took longer than 9 s", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health": { "get": { "tags": [ "meta" ], "operationId": "health", "summary": "Liveness and deployed version", "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "version" ], "properties": { "ok": { "const": true }, "version": { "type": "string", "examples": [ "0.7.2" ] } } } } } } } } }, "/api/auth/status": { "get": { "tags": [ "meta" ], "operationId": "authStatus", "summary": "Current limits and sign-in / Pro availability", "security": [ {} ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "google": { "type": "boolean", "description": "Google sign-in (free key minting) is configured" }, "freeApi": { "type": "boolean" }, "limits": { "type": "object", "properties": { "anonymousPerMin": { "type": "integer" }, "freePerMin": { "type": "integer" }, "freePerDay": { "type": "integer" }, "proPerMin": { "type": "integer" }, "proPerDay": { "type": "integer" }, "sharedChecksPerDay": { "type": "integer" }, "sharedAnonymousChecksPerDay": { "type": "integer" } } }, "proCheckout": { "type": "boolean" }, "proCheckoutUrl": { "type": "string", "format": "uri" }, "dailyCounter": { "type": "string", "enum": [ "durable_object", "unavailable" ] } } } } } }, "405": { "description": "`method_not_allowed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "tags": [ "mcp" ], "operationId": "mcp", "summary": "Remote MCP server (Streamable HTTP, JSON-RPC 2.0)", "description": "Model Context Protocol endpoint. Stateless, JSON responses only (no SSE, no Mcp-Session-Id). Supported protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Modern (2026-07-28) requests carry params._meta and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; legacy clients use initialize. Tool: check_domain. Same keys and limits as /api/check; each tools/call counts as one check. Body max 65536 bytes; legacy batches max 10 messages with at most one tools/call.", "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" ] } }, { "name": "Mcp-Method", "in": "header", "required": false, "description": "Required for 2026-07-28; must equal the body method", "schema": { "type": "string" } }, { "name": "Mcp-Name", "in": "header", "required": false, "description": "Required for 2026-07-28 tools/call; must equal params.name", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcMessage" }, { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/JsonRpcMessage" } } ] } } } }, "responses": { "200": { "description": "JSON-RPC response (or batch of responses). Tool failures, including rate limits, are results with isError: true.", "content": { "application/json": { "schema": { "type": [ "object", "array" ] } } } }, "202": { "description": "Notification(s) accepted; no body" }, "400": { "description": "Parse error (-32700), invalid request (-32600), header mismatch (-32020), unsupported protocol version (-32022) or missing _meta (-32602)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Invalid API key (JSON-RPC error, data.code = invalid_api_key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Origin header present but not allowed", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown method in a 2026-07-28 request (-32601)", "content": { "application/json": { "schema": { "type": "object" } } } }, "413": { "description": "Body larger than the cap", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Too many non-check MCP messages from this IP", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Unexpected internal error (`internal_error`); per-message failures are JSON-RPC -32603 inside a 200 response instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Key storage unavailable", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "mcp" ], "operationId": "mcp_get_not_allowed", "summary": "Not supported (stateless server: no SSE stream, no sessions)", "responses": { "405": { "description": "Always 405 with `Allow: POST, OPTIONS` and a JSON-RPC error body", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "mcp" ], "operationId": "mcp_delete_not_allowed", "summary": "Not supported (stateless server: no SSE stream, no sessions)", "responses": { "405": { "description": "Always 405 with `Allow: POST, OPTIONS` and a JSON-RPC error body", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }