API Documentation

Overview

The DNSai REST API provides programmatic access to your DNS intelligence data. Use it to integrate domain monitoring, scan results, WHOIS data, and change history into your existing tools and workflows.

The API is available on Enterprise plans and above:

• Enterprise ($99/mo) — 100 requests/min, 10,000 calls/day
• Enterprise Max ($2,500/mo) — 500 requests/min, 50,000 calls/day
• Enterprise Max Premium ($5,000/mo) — 2,000 requests/min, 200,000 calls/day

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

Create a free account   or log in →

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 3 active API keys at a time.

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 provide them to your AI assistant for context-aware code generation.

Endpoints Reference

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

API Root

Domains

Dashboard

Exports

API Keys

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",
    "previous": null
  },
  "errors": []
}

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']})")

Rate Limits & Quotas

API access is rate-limited per API key (per minute) and quota-limited per user (per day).

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 3 active keys to facilitate zero-downtime rotation

Network Security

• Always use HTTPS — the API does not accept HTTP connections
• Consider restricting API access to specific IP addresses using your firewall
• 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

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.

WHOIS Fields

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

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/.

Integrations

Step-by-step guides for integrating DNSai with your existing platforms. Each guide includes setup instructions, code examples, and field mapping references.