Docs menu

Compare view

POST /v1/compare

Price
Cache
MCP tool
compare_domains

Request body

Request body fields
NameTypeDescription
domains (required)array of string2 to 4 domains to compare, such as example.com (each once)
tools (required)array of string1 to 4 tool ids to run on every domain, such as ssl-checker
freshbooleanSkip the cache for every cell and ask again. Costs the same as cached answers.

Response

Response fields
NameTypeDescription
domains (required)array of stringThe domains as checked (ASCII form), column order
tools (required)array of string
status (required)"ok" | "partial" | "error"
cells (required)array of objectOne cell per tool and domain, tool order first
rows (required)array of objectFindings lined up across the domains; differing rows first
scores (required)array of objectEach tool's score per domain (graded tools)
summary (required)string
credits_used (required)integer
credits_remaining (required)integer or null
data (required)objectThis tool's result

Errors

  • 400 Not 2 to 4 domains or 1 to 4 tools, a repeated domain or tool, a tool that can't be compared (the message lists the ones that can), or a domain we can't look up (`invalid_request`, `invalid_domain`)
  • 401 Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
  • 402 Your balance is below the price of every cell together (`insufficient_credits`)
  • 403 The website's free checks don't cover compare; sign in (`sign_in_required`)
  • 413 The body is larger than 64 KiB (`invalid_request`)
  • 429 More than 30 comparisons in an hour, or too many `fresh` cells; wait for the seconds in Retry-After (`rate_limited`)
  • 500 Unexpected error (`internal_error`)
  • 502 No cell got an answer from its sources; nothing was charged (`source_unavailable`)

Example

curl

curl
curl -X POST "https://api.dnssuper.com/v1/compare" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["example.com","example.net"],"tools":["ssl-checker","email-checker"]}'

Python

Python (httpx)
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.post("/v1/compare", json={
    "domains": ["example.com", "example.net"],
    "tools": ["ssl-checker", "email-checker"],
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])

TypeScript

TypeScript (fetch)
const response = await fetch("https://api.dnssuper.com/v1/compare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"domains":["example.com","example.net"],"tools":["ssl-checker","email-checker"]}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);

MCP

MCP tool call
{
  "tool": "compare_domains",
  "arguments": {
    "domains": [
      "example.com",
      "example.net"
    ],
    "tools": [
      "ssl-checker",
      "email-checker"
    ]
  }
}