# Compare view API

`POST /v1/compare`

- Price: see the tool page
- Cache: none
- MCP tool: `compare_domains`

Run the same 1 to 4 tools on 2 to 4 domains and see the results side by side: every tool's result per domain (`cells`, tool order first), the findings lined up across the domains with the ones that differ first (`rows`), each graded tool's score per domain (`scores`) and a one-line summary. Each cell costs its tool's price, cached cells the same (ssl-checker at 1 plus email-checker at 2 on 3 domains is 9 credits); a cell that gets no answer costs nothing and carries an `error` instead of an `envelope`. The whole comparison is checked against your balance first (402) and charged once. With `stream=true` the answer is a 202 with an `events_url`: the total is held, each cell arrives as a `section` event (`cell`) as soon as it is in, and the last event is the `result`. A retry with the same `X-Request-Id` returns the stored comparison for 24 hours without charging again. Needs an account: the website's free checks don't cover it. At most 30 comparisons an hour.

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | array of string | yes | 2 to 4 domains to compare, such as example.com (each once) |
| `tools` | array of string | yes | 1 to 4 tool ids to run on every domain, such as ssl-checker |
| `fresh` | boolean | no | Skip the cache for every cell and ask again. Costs the same as cached answers. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | array of string | yes | The domains as checked (ASCII form), column order |
| `tools` | array of string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `cells` | array of object | yes | One cell per tool and domain, tool order first |
| `rows` | array of object | yes | Findings lined up across the domains; differing rows first |
| `scores` | array of object | yes | Each tool's score per domain (graded tools) |
| `summary` | string | yes |  |
| `credits_used` | integer | yes |  |
| `credits_remaining` | integer or null | yes |  |
| `data` | object | yes | This 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

```sh
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
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"])
```

```ts
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

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