API Documentation

Overview

DNSai puts your DNS intelligence wherever you work: in your own code through the REST API, in your AI assistant through the MCP server, in your CRM and SIEM, and in your systems the moment something changes, through signed webhooks. Domains, MX and email gateways, SPF, DKIM and DMARC, nameservers, TXT records, WHOIS, website technologies, subdomains, Organization Deep Scans and every DNS change are all available.

What’s new

• AI tools: step-by-step setup for Claude, ChatGPT, Microsoft & GitHub Copilot, Gemini, Perplexity, Grok, Cursor, Claude Code, Codex, Meta Muse, Ollama and more. See AI & Integrations.
• Every Enterprise feature over the API and MCP: subdomains, Organization Deep Scan reports, website scans, live WHOIS, parsed email security, technology breakdowns, folders and tags, and lookups of up to 100 domains in one call.
• DNS changes, filtered: by field, folder, tag, favorite, email-gateway switch, vendor or record text, with newest-first cursors and a stats endpoint. See DNS Changes.
• Webhooks: new changes are pushed to your HTTPS endpoint, signed with HMAC-SHA256. See Webhooks.
• Safer keys: up to 10 keys, each with an optional expiry and IP allowlist, plus a read-only switch for API keys and AI assistants.
• OpenAPI 3.1: /api/v1/openapi.json for Copilot Studio, Postman, function calling and client generators.

The API and MCP server are included on Enterprise plans and above:

• Enterprise ($499/mo) — 100 requests/min, 10,000 calls/day
• Enterprise Max (Contact for pricing) — 500 requests/min, 50,000 calls/day
• Enterprise Max Premium (Contact for pricing) — 2,000 requests/min, 200,000 calls/day

Limits belong to the subscription: everyone in your organization shares them, and every call counts from the first one.

All API endpoints are under https://app.dnsai.com/api/v1/ and return JSON responses in a consistent envelope format.

Create a free account   See plans →   or log in →

AI & Integrations

Prefer a traditional API? Jump to REST API and webhooks for curl, Python and JavaScript, Postman, signed webhooks and Excel, Power BI or Google Sheets, or straight to the endpoint reference.

Connect DNSai to the AI tools your team already uses, then ask in plain English: “Which of my target accounts moved to Microsoft 365 this month?”, “Summarize DMARC changes across my portfolio this week” or “Run an attack-surface review of example.com and its subdomains.” Each guide takes a few minutes.

AI assistants

• ChatGPT OpenAI Connect DNSai to ChatGPT as a custom MCP app with OAuth sign-in. Sign in with OAuth
• Claude Anthropic Add DNSai as a custom connector in claude.ai, Claude Desktop and mobile. Sign in with OAuth
• Google Gemini Google Use DNSai from Antigravity CLI, the Gemini API, or as a custom app in Gemini. MCP with API key
• Grok xAI Give Grok DNSai tools via the xAI API, Grok Build CLI or grok.com connectors. MCP with API key
• Meta Muse Meta Add DNSai to the Muse app as a custom connector, or to Muse Code and the Meta Model API. MCP with API key
• Perplexity Perplexity Add DNSai as a custom remote connector in Perplexity. Sign in with OAuth
• Grok Bot xAI Add DNSai to a Grok Bot personal agent as a custom MCP server. MCP with API key
• Mistral Le Chat Mistral AI Add DNSai as a custom MCP connector in Le Chat. Sign in with OAuth

Coding tools

• Claude Code Anthropic One command adds DNSai to Claude Code in your terminal. MCP with API key
• Cursor Anysphere Add DNSai to Cursor's mcp.json and use it from Agent. MCP with API key
• OpenAI Codex OpenAI Add DNSai to the Codex CLI with three lines of config.toml. MCP with API key
• Windsurf Cognition Add DNSai to Windsurf (Devin Desktop) Cascade. MCP with API key

Microsoft

• GitHub Copilot GitHub / Microsoft Use DNSai in Copilot agent mode in VS Code, JetBrains and the Copilot coding agent. MCP with API key
• Microsoft Copilot Studio Microsoft Add DNSai as an MCP tool to a Copilot Studio agent for Microsoft 365 Copilot and Teams. MCP with API key
• Microsoft Copilot (consumer) Microsoft The consumer Copilot app has no custom connectors; use Microsoft 365 Copilot via Copilot Studio. OpenAPI actions

Local and open models

• Ollama and local models Ollama · Qwen · DeepSeek · Llama Run Qwen, DeepSeek, Llama or Hermes locally and give them DNSai tools. Local bridge
• DeepSeek DeepSeek Use DNSai with DeepSeek's API or local DeepSeek models through function calling. Local bridge
• Hermes Agent Nous Research Add DNSai to Nous Research's Hermes Agent, with local or hosted Hermes models. MCP with API key
• LM Studio LM Studio Add DNSai to LM Studio's mcp.json and use it with any local model. MCP with API key
• Open WebUI Open WebUI Connect DNSai as an MCP tool server in Open WebUI. MCP with API key

Automation and more

• n8n n8n Give n8n AI agents DNSai tools with the MCP Client Tool node. MCP with API key
• Zapier Zapier Call DNSai tools from Zaps with Zapier's MCP Client, or trigger Zaps from DNSai webhooks. MCP with API key
• Other MCP clients VS Code · Zed · Cline · Roo · Continue · JetBrains · Amazon Q · Goose Any MCP client that supports Streamable HTTP and an Authorization header works with DNSai. MCP with API key

REST API and webhooks

• REST API curl · Python · JavaScript · any language The traditional route: plain HTTPS and JSON from any language, script or server. REST API
• Webhooks Any HTTPS endpoint Have new DNS changes pushed to your server, signed with HMAC-SHA256. REST API
• Excel, Power BI and Google Sheets Microsoft · Google Pull your domains and DNS changes into a spreadsheet or BI dashboard that refreshes. REST API
• Postman and API clients Postman · Insomnia · Bruno Import the OpenAPI spec and try every endpoint without writing code. REST API

Platforms and data pipelines

Browse every guide: all AI integrations →

MCP Server

The DNSai MCP server is a remote Model Context Protocol server. Any MCP-capable assistant, including Claude, ChatGPT, Copilot, Cursor, Gemini, Perplexity and Grok, can read your domains, DNS and email-security posture, WHOIS, subdomains, website technologies, Deep Scan reports and change history, and act on them within your plan limits.

Server URL

https://mcp2.dnsai.com/mcp

Connect in under a minute

Claude, ChatGPT, Perplexity, Mistral Le Chat (OAuth, no key): add a custom connector with the URL above, sign in to DNSai and approve access. In Claude: Settings → Connectors → Add custom connector.

Claude Code, Codex, Cursor, VS Code / GitHub Copilot, Gemini and other desktop or command-line tools (API key): keep the key in an environment variable and send it as a header. For example, in Claude Code:

claude mcp add --transport http dnsai https://mcp2.dnsai.com/mcp \
  --header "Authorization: Bearer $DNSAI_API_KEY"

Then ask: “Use DNSai whoami and tell me my plan.” Exact steps for each tool are in the AI integration guides.

Authentication

Tools

Guided prompts: audit_domain, triage_recent_changes, weekly_change_briefing, vendor_migration_watch, compare_spf_dmarc. Resources: dnsai://domains, dnsai://dashboard/summary, dnsai://changes/recent, dnsai://domain/{name}.

Built to be safe with AI

• Every request is scoped to your own account’s data. Deletes, billing and admin actions are never exposed.
• Each tool is labelled read-only or not, so your assistant can ask before it changes anything.
• A Deep Scan spends credits, so it takes two steps: estimate_org_scan returns the cost and a 10-minute confirmation token, and start_org_scan only runs with that token after you approve.
• Turn on read-only mode for your account or your whole organization under Settings → API Keys, and assistants can only look things up.
• DNS, WHOIS and website text is written by each domain’s owner, so assistants are told to treat it as data, never as instructions.
• MCP calls share your organization’s limits and are logged with the name of the connecting app.

Authentication

The API uses Bearer token authentication with API keys. Each API key is a long random string prefixed with dnsai_live_.

Creating an API Key

API access is available on Enterprise plans. Create an account or log in, then:

1. Go to Settings > API Keys
2. Click Create New API Key
3. Give your key a descriptive name (e.g., "Production Server")
4. Copy the key immediately — it is shown only once and cannot be retrieved later

You can have up to 10 active API keys at a time — use one per tool or integration so you can revoke them separately. Every key draws from the same usage pool: your plan’s limits are shared by all members of your organization, and extra keys or users don’t add allowance.

Using Your API Key

Include your API key in the Authorization header of every request:

Authorization: Bearer dnsai_live_YOUR_API_KEY_HERE

Getting Started

Get up and running in minutes. The examples below cover the most common operations. All responses use a consistent JSON envelope with data, meta, and errors fields.

1. Set Up Your API Key

# Store your key in an environment variable — never hardcode it
export DNSAI_API_KEY="dnsai_live_YOUR_KEY_HERE"

2. Make Your First Request

curl -H "Authorization: Bearer $DNSAI_API_KEY" \
     https://app.dnsai.com/api/v1/domains/

import os, requests

API_KEY = os.environ["DNSAI_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}

# List your domains (default: 250 per request, max: 5000)
response = requests.get(
    "https://app.dnsai.com/api/v1/domains/",
    headers=headers,
    params={"limit": 1000},  # fetch up to 1000
)
result = response.json()
print(f"Got {len(result['data'])} of {result['meta']['total_count']} domains")

for domain in result["data"]:
    print(domain["domain"], domain["email_gateway"])

const API_KEY = "dnsai_live_YOUR_KEY";

const response = await fetch("https://app.dnsai.com/api/v1/domains/?limit=1000", {
  headers: { "Authorization": `Bearer ${API_KEY}` },
});
const { data, meta } = await response.json();
console.log(`Got ${data.length} of ${meta.total_count} domains`);
data.forEach(d => console.log(d.domain, d.email_gateway));

3. Fetch All Pages

For large datasets, follow meta.next to iterate through all pages. Quotas count API calls, not rows — fetching 5,000 rows counts as 1 call.

url = "https://app.dnsai.com/api/v1/domains/?limit=5000"
all_domains = []

while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    all_domains.extend(data["data"])
    url = data["meta"].get("next")  # None when no more pages

print(f"Fetched {len(all_domains)} of {data['meta']['total_count']} domains")

4. Common Operations

curl -H "Authorization: Bearer $DNSAI_API_KEY" \
     https://app.dnsai.com/api/v1/domains/123/

curl -X POST \
     -H "Authorization: Bearer $DNSAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domains": ["example.com", "example.org"]}' \
     https://app.dnsai.com/api/v1/domains/

curl -H "Authorization: Bearer $DNSAI_API_KEY" \
     https://app.dnsai.com/api/v1/dashboard/summary/

curl -H "Authorization: Bearer $DNSAI_API_KEY" \
     "https://app.dnsai.com/api/v1/domains/?email_gateway=Google+Workspace&limit=5000"

AI-Assisted Development

Use AI tools like Claude, ChatGPT, or GitHub Copilot to build your DNSai integration faster. Download the reference files below and give them to your assistant for context-aware code generation. To let an assistant use your data directly instead of writing code, connect it to the MCP server.

Endpoints Reference

All endpoints are relative to https://app.dnsai.com/api/v1/

API Root

Domains

Fresh Data on Demand

These start work right away and count against your plan’s on-demand limits. They are refused while read-only mode is on.

Organization Deep Scan

A Deep Scan maps a domain and all its subdomains: DNS, email security, website technologies and findings. Starting one spends credits, so it takes two calls.

Portfolio

Dashboard

Exports

Account Management (signed-in session only)

These endpoints use your signed-in session, not an API key, so a leaked key can’t create more keys or change settings. Most people use Settings → API Keys instead.

Response Envelope

All responses are wrapped in a consistent JSON envelope:

{
  "status": "ok",
  "data": [ ... ],
  "meta": {
    "total_count": 1234,
    "limit": 250,
    "offset": 0,
    "next": "https://app.dnsai.com/api/v1/domains/?limit=250&offset=250"
  },
  "errors": []
}

meta.next and meta.previous are present only when another page exists: previous is absent on the first page and next on the last, rather than being sent as null.

For errors:

{
  "status": "error",
  "data": null,
  "meta": {},
  "errors": [
    {
      "code": "authentication_required",
      "detail": "Authentication credentials were not provided."
    }
  ]
}

Pagination

List endpoints use limit/offset pagination designed for programmatic access. The default limit is 250, maximum 5,000 results per request.

The response meta object includes total_count so you know how many results exist. Follow meta.next to iterate, or calculate offsets directly.

# Pull up to 5000 domains per request — no UI pagination limits
url = "https://app.dnsai.com/api/v1/domains/?limit=5000"
all_domains = []

while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    all_domains.extend(data["data"])
    url = data["meta"].get("next")

print(f"Fetched {len(all_domains)} of {data['meta']['total_count']} domains")

# Jump directly to any position in the result set
response = requests.get(
    "https://app.dnsai.com/api/v1/domains/",
    headers=headers,
    params={"limit": 1000, "offset": 2000}  # rows 2001–3000
)
data = response.json()
print(f"Got {len(data['data'])} domains (offset 2000 of {data['meta']['total_count']})")

DNS Changes

DNSai tracks six fields on every domain: mx, email_gateway, dmarc_policy_p, spf, ns and txt. These filters work on /api/v1/changes/, /api/v1/changes/stats/ and the MCP list_changes tool:

value searches (and, on whole-database plans, vendor and gateway searches) cover up to 31 days at a time; without since they use the last 7 days. Add a domain, folder_id or tag filter to search further back.

curl -H "Authorization: Bearer $DNSAI_API_KEY" \
  "https://app.dnsai.com/api/v1/changes/?order=desc&gateway_to=Mimecast&since=2026-10-01"

Webhooks

Add up to three HTTPS endpoints under Settings → API Keys → DNS Change Webhooks. About every 15 minutes DNSai POSTs new changes on your domains (optionally only some fields), oldest first, in batches of up to 200:

{"event": "dns.changes", "webhook_id": "…", "count": 2, "has_more": false,
 "next_since_id": 123456, "changes": [ { "id": 123455, "domain": "example.com",
   "field_name": "email_gateway", "summary": "Email gateway: Proofpoint → Microsoft 365", … } ]}

Each request carries X-DNSai-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with your signing secret. Reject anything older than five minutes or with a signature that doesn’t match:

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Answer with any 2xx within 10 seconds. Redirects are not followed. Ten failed deliveries in a row pause the webhook and leave a notice in your notification bell; resume it from Settings once the endpoint is fixed. Endpoints must be public HTTPS on port 443 or 8443.

Rate Limits & Quotas

Limits belong to your subscription. Every member of your organization and every key draws from the same per-minute limit and daily quota, and every call counts from the first one. Extra keys or users don’t add allowance. (Organizations set to per-seat limits split the plan’s allowance evenly across included seats.) The MCP server has its own allowance, also shared by the organization; ask your assistant to run whoami to see it.

Rate Limit Headers

Every API response includes these headers:

Handling 429 Responses

When you exceed a rate limit or quota, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

import time

def api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        return response
    raise Exception("Max retries exceeded")

Error Handling

The API uses standard HTTP status codes and returns errors in the envelope format.

Error Response Format

{
  "status": "error",
  "data": null,
  "meta": {},
  "errors": [
    {
      "code": "rate_limit_exceeded",
      "detail": "Rate limit exceeded (100 requests per minute). Please retry after 45 seconds."
    }
  ]
}

Troubleshooting

• 401 errors: Verify your API key is correct and has not been revoked. Check that the header format is exactly Authorization: Bearer dnsai_live_...
• 403 errors: Your plan may not include API access. Upgrade to an Enterprise plan.
• 404 errors: The domain ID must belong to your account. Use the list endpoint to find valid IDs.
• 429 errors: Implement exponential backoff and respect the Retry-After header.

Security Best Practices

Key Storage

• Store API keys in environment variables, never in source code
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) for production deployments
• Never commit API keys to version control — add them to .gitignore or .env files

# .env file (never commit this)
DNSAI_API_KEY=dnsai_live_YOUR_KEY_HERE

# Python usage
import os
API_KEY = os.environ["DNSAI_API_KEY"]

Key Rotation

• Rotate API keys periodically (every 90 days recommended)
• Create a new key before revoking the old one to avoid downtime
• Update all systems using the old key before revoking it
• You can have up to 10 active keys, which allows one key per tool plus zero-downtime rotation

Network Security

• Always use HTTPS — the API does not accept HTTP connections
• Restrict server keys to your own IP addresses or ranges with the key’s IP allowlist (keys used by cloud AI services should not be IP-restricted)
• Give keys an expiry, and use one key per tool or integration so you can revoke just that one
• Turn on read-only mode under Settings → API Keys if your keys and assistants only need to look things up
• Monitor the "Last Used" timestamp in Settings to detect unauthorized usage

Monitoring

• Check the API Keys tab in Settings for usage stats
• Monitor rate limit headers to stay within your plan limits
• Set up alerts if your daily quota usage exceeds 80%
• Revoke keys immediately if you suspect unauthorized access

Complete Field Reference

Every field available from the DNSai API, organized by endpoint. Use this reference when building integrations to know exactly what data is available.

Domain List Fields

Returned by GET /api/v1/domains/ for each domain in the data array.

Domain Detail Fields

Returned by GET /api/v1/domains/{id}/ — includes all list fields plus:

Scan Result Fields

Returned by GET /api/v1/domains/{id}/scan-results/ and nested as scan_result in the domain detail response. This is the complete DNS intelligence dataset for a domain.

Core DNS Records

Email Detection

Country, region, city, coordinates and ASN fields (mx_server_*, a_server_*, WHOIS ip_geolocation) are resolved from the IP address. This product includes IP2Location LITE data available from https://lite.ip2location.com.

MX Server Geolocation

A Record Server Geolocation

DKIM

SPF Analysis

Change Tracking (Built into Scan Result)

Change History Fields

Returned by GET /api/v1/domains/{id}/changes/ and nested as change_history in the domain detail response.

Record values come from public DNS and are written by the domain’s owner. Treat them as data: never execute them or pass them to an AI model as instructions.

WHOIS Fields

Returned by GET /api/v1/domains/{id}/whois/ and nested as whois in the domain detail response.

Website Fields

Returned by GET /api/v1/domains/{id}/website/ and nested as website in the domain detail response. Produced by a single fetch of the site's public homepage (no JavaScript executed) plus IP/ASN correlation. Website results are shared per domain, exactly like DNS results. Scans are triggered from the Website Technologies tab in the app (10 per user per hour); the list endpoint accepts ?web_technology= and ?site_type= filters and every list row carries site_type and web_platform.

Dashboard Summary Fields

Returned by GET /api/v1/dashboard/summary/ — aggregated statistics across your domain portfolio.

Export Job Fields

Returned by GET /api/v1/exports/ and POST /api/v1/exports/.

API Key Fields

Returned by GET /api/v1/keys/ and POST /api/v1/keys/.