# API reference

Every endpoint that isn't a tool. Tools have their own pages under /docs/tools. Send your API key as `Authorization: Bearer <key>` on every call unless it says otherwise.

## Account

### GET /v1/account

**Account, balance and recent usage.** Your account, credit balance and last 20 calls, newest first. No charge.

No charge.

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | object | yes |  |
| `account.id` | string | yes |  |
| `account.email` | string | yes |  |
| `account.plan` | string | yes |  |
| `account.status` | "active" | "suspended" | yes |  |
| `credits` | object | yes |  |
| `credits.balance` | integer | yes |  |
| `recent_usage` | array of object | yes | Last 20 usage events, newest first |
| `recent_usage.time` | string | yes |  |
| `recent_usage.tool` | string | yes |  |
| `recent_usage.target` | string | yes |  |
| `recent_usage.credits` | integer | yes |  |
| `recent_usage.cached` | boolean | yes |  |
| `recent_usage.status` | "ok" | "partial" | "error" | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/account" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/account")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/account`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/account/events

**Account events.** Server-sent events for your account: `usage` after every charged or free call (tool, usage target, credits, cached, status, duration), `job` when a job starts, makes progress or ends, and `monitor` when a monitor runs. Reconnect with `Last-Event-ID` to resume; without it the stream starts from now. At most 3 open per account. No charge.

No charge.

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

```sh
curl "https://api.dnssuper.com/v1/account/events" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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,
)
with client.stream("GET", "/v1/account/events", timeout=None) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/account/events`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(value);
}
```

## Jobs

### GET /v1/jobs

**Your jobs.** The account's jobs, newest first: tool jobs and bulk checks, with their progress, credits and estimated time left. Filter with `status` and `kind`; page with `cursor` (the `next_cursor` of the previous page). No charge.

No charge.

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no | `next_cursor` from the previous page |
| `limit` | integer | no | Jobs per page |
| `status` | "unfinished" | "finished" | "all" | no | Which jobs to list |
| `kind` | "tool" | "bulk" | "all" | no | Tool jobs, bulk checks or both |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes |  |
| `items.id` | string | yes |  |
| `items.tool` | string | yes |  |
| `items.status` | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | yes |  |
| `items.total` | integer | yes | Rows in the job |
| `items.done` | integer | yes | Rows with a result (charged) |
| `items.failed` | integer | yes | Rows whose sources didn't answer (not charged) |
| `items.credits_reserved` | integer | yes | Credits held when the job was submitted |
| `items.credits_used` | integer | yes | Credits charged so far; the rest of the reservation returns when it ends |
| `items.created_at` | string | yes |  |
| `items.started_at` | string or null | yes |  |
| `items.finished_at` | string or null | yes |  |
| `items.progress` | object or null | no | The running row's own progress, such as pages crawled; null when none |
| `items.label` | string or null | no | The label given when it was submitted |
| `items.bulk` | boolean | no | True for a bulk check |
| `items.estimated_remaining_s` | integer or null | no | Seconds until the job should finish: from the rows done so far once 5 have finished, else from the estimate made at submission; null when finished or unknown |
| `next_cursor` | string or null | yes | Pass as `cursor` for the next page; null on the last page |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/jobs" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/jobs")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/jobs`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/jobs/{job_id}

**Job status.** Progress and credits of a job. `credits_reserved` were held when it was submitted; `credits_used` counts rows with a result (failed and skipped rows are free), and the rest of the reservation returns to your balance when the job ends. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The job's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `tool` | string | yes |  |
| `status` | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | yes |  |
| `total` | integer | yes | Rows in the job |
| `done` | integer | yes | Rows with a result (charged) |
| `failed` | integer | yes | Rows whose sources didn't answer (not charged) |
| `credits_reserved` | integer | yes | Credits held when the job was submitted |
| `credits_used` | integer | yes | Credits charged so far; the rest of the reservation returns when it ends |
| `created_at` | string | yes |  |
| `started_at` | string or null | yes |  |
| `finished_at` | string or null | yes |  |
| `progress` | object or null | no | The running row's own progress, such as pages crawled; null when none |
| `label` | string or null | no | The label given when it was submitted |
| `bulk` | boolean | no | True for a bulk check |
| `estimated_remaining_s` | integer or null | no | Seconds until the job should finish: from the rows done so far once 5 have finished, else from the estimate made at submission; null when finished or unknown |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/jobs/<job_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/jobs/<job_id>")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/jobs/<job_id>`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/jobs/{job_id}/items

**Job rows and results.** A job's rows in order, with each row's status, credits, error and result envelope. Page with `after` (the last row you have) and `limit`; results are kept for 7 days. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The job's ID |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `after` | integer | no | Return rows after this row number |
| `limit` | integer | no | Rows per page |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes |  |
| `items.row` | integer | yes | Row number, starting at 1 |
| `items.target` | string | yes |  |
| `items.status` | "queued" | "done" | "failed" | "skipped" | yes |  |
| `items.cached` | boolean | yes |  |
| `items.credits` | integer | yes |  |
| `items.error` | object or null | yes |  |
| `items.result` | object or null | yes | The row's result envelope; null until it is done, and after 7 days |
| `next_after` | integer or null | yes | Pass as `after` for the next page; null on the last page |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/jobs/<job_id>/items" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/jobs/<job_id>/items")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/jobs/<job_id>/items`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/jobs/{job_id}/cancel

**Cancel a job.** Stops a queued or running job: rows already done stay charged, the rest are skipped and their held credits return to your balance. The job shows `cancelling` until the worker settles it. Cancelling a finished job returns it unchanged. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The job's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `tool` | string | yes |  |
| `status` | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | yes |  |
| `total` | integer | yes | Rows in the job |
| `done` | integer | yes | Rows with a result (charged) |
| `failed` | integer | yes | Rows whose sources didn't answer (not charged) |
| `credits_reserved` | integer | yes | Credits held when the job was submitted |
| `credits_used` | integer | yes | Credits charged so far; the rest of the reservation returns when it ends |
| `created_at` | string | yes |  |
| `started_at` | string or null | yes |  |
| `finished_at` | string or null | yes |  |
| `progress` | object or null | no | The running row's own progress, such as pages crawled; null when none |
| `label` | string or null | no | The label given when it was submitted |
| `bulk` | boolean | no | True for a bulk check |
| `estimated_remaining_s` | integer or null | no | Seconds until the job should finish: from the rows done so far once 5 have finished, else from the estimate made at submission; null when finished or unknown |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/jobs/<job_id>/cancel" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/jobs/<job_id>/cancel", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/jobs/<job_id>/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/jobs/{job_id}/events

**Job events.** Server-sent events for a job: `progress` with `{done, failed, total}` after each row, then one `done` event with the job (as `GET /v1/jobs/{id}`), after which the stream ends. A finished job's stream sends `done` at once. Reconnect with `Last-Event-ID` to resume. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | yes | The job's ID |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

```sh
curl "https://api.dnssuper.com/v1/jobs/<job_id>/events" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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,
)
with client.stream("GET", "/v1/jobs/<job_id>/events", timeout=None) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/jobs/<job_id>/events`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(value);
}
```

## Bulk

### POST /v1/bulk/{tool}

**Bulk check.** Check many rows in one job. Send JSON with exactly one of `targets` (names), `rows` (objects of the tool's own inputs) or `csv` (a CSV file's text with a header row), or upload the file itself as `text/csv` with job-wide options as query parameters. `options` apply to every row; `fresh`, variant and per-unit options are job-wide only. Every row is checked before anything is charged: with `dry_run=true` the answer lists the columns, the row errors (with line numbers), a preview, the credits the job would hold and the longest time it could take, and nothing is reserved. Add `skip_invalid=true` to run only the valid rows. The job holds the price of every row and charges only rows that get a result. Follow it at `job_url`, read results at `items_url`, cancel it with `POST /v1/jobs/{id}/cancel`, or get a notice on an alert channel with `notify`. Bulk checks unlock after your first credit purchase or plan.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes | Registry id of the tool |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `dry_run` | boolean | no | Show the rows, errors, credits and time without starting the job |
| `skip_invalid` | boolean | no | Run only the valid rows instead of refusing the job |

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `targets` | array of any or null | no | Names to check, one per row |
| `rows` | array of object or null | no | Rows of the tool's own input properties |
| `csv` | string or null | no | The text of a CSV file: a header naming the tool's inputs, one row per check |
| `options` | object | no | Job-wide parameters for every row: `fresh`, variant and per-unit options, and any shared tool parameter |
| `label` | string or null | no | Your name for the job |
| `notify` | object or null | no | Send a notice to this alert channel when the job finishes |
| `check_ownership` | boolean | no | Dry runs only: also check the TXT ownership records (subdomain takeover) |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes |  |
| `rows` | integer | yes | Rows sent |
| `unique` | integer | yes | Valid rows that would run after removing duplicates |
| `duplicates_removed` | integer | yes |  |
| `invalid` | integer | yes | Rows with an error |
| `errors` | array of object | yes | The first 100 row errors |
| `errors.row` | integer | yes | CSV line (1-based) or position in the list |
| `errors.column` | string or null | yes |  |
| `errors.message` | string | yes |  |
| `columns` | array of string | yes | The input each column was read as |
| `preview` | array of object | yes | The first 5 valid rows |
| `preview.row` | integer | yes |  |
| `preview.target` | string | yes |  |
| `preview.options` | object | yes |  |
| `limit` | integer | yes | The most rows one bulk check with this tool may have |
| `credits` | integer | yes | Credits the job would hold when it starts |
| `balance` | integer | yes | Your balance now |
| `estimated_max_s` | integer | yes | The longest the job could take, if every row is as slow as it can be |
| `unverified` | array of string | yes | Domains still needing their TXT ownership record (at most 20) |
| `records` | array of object | no | The TXT record to publish for each of them |
| `records.domain` | string | yes |  |
| `records.record_name` | string | yes |  |
| `records.record_value` | string | yes |  |
| `verification_checked` | boolean | yes | True when the records were looked up (`check_ownership`) |

Errors:

- `400` The tool has no bulk checks, too many or no rows, invalid rows (listed in `error.details.errors`), an unknown or job-wide column, or a list that can't finish in time (`invalid_request`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `402` Balance below the call's price (`insufficient_credits`)
- `403` The website's key without a signed-in user, an account without a credit purchase or paid plan yet, or a dangling-record check without the TXT ownership records (`sign_in_required`, `bulk_locked`, `verification_required`)
- `413` The body is larger than 2 MiB of JSON, or 1 MiB as `text/csv` (`invalid_request`)
- `429` More than 10 bulk checks or 30 previews in an hour, 3 unfinished bulk checks, or too many `fresh` calls; wait for the seconds in Retry-After (`rate_limited`, `too_many_jobs`)
- `500` Unexpected error (`internal_error`)
- `503` Bulk checks are busy site-wide; try again after Retry-After (`bulk_busy`)

```sh
curl -X POST "https://api.dnssuper.com/v1/bulk/<tool>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/bulk/<tool>", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/bulk/<tool>", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/verifications/record

**Ownership record.** The TXT record that proves your account controls a domain, for bulk dangling-record checks. Publish it at `record_name` with the value `record_value`; one record covers every name under the registrable domain. Free; nothing is stored.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | The registrable domain the record proves |
| `record_name` | string | yes | Where to publish the TXT record |
| `record_value` | string | yes | The TXT record's exact value |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/verifications/record" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
```

```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/verifications/record", json={
    "domain": "example.com",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/verifications/record", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"domain":"example.com"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/verifications/check

**Check an ownership record.** Whether the TXT ownership record for a domain is published, asked of our resolver and then of the domain's own nameservers, so a record you just added counts. Free; at most 60 checks an hour.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes |  |
| `verified` | boolean | yes | True when the record is published with the right value |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/verifications/check" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
```

```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/verifications/check", json={
    "domain": "example.com",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/verifications/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"domain":"example.com"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

## Streams

### POST /v1/streams

**Start a streamed tool call.** Start a tool call whose result arrives section by section over server-sent events. The body names the tool (`dns-lookup`) and its input, the same parameters as the tool's own endpoint (`domain`, `types`); `fresh` skips the cache. Input, credits and limits are checked before the 202, so those errors come back here as normal JSON errors. Then open `stream_url` (an `EventSource` works; no API key needed, the stream id is the access). The call costs what the tool's own endpoint costs and is charged once, when the result is complete, whether or not anyone is listening. A retry with the same `X-Request-Id` gets a stream holding only the stored result, marked `replayed`, with no new charge.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes | Registry id of the tool |
| `input` | object | no | The tool's parameters, as for its own endpoint |
| `fresh` | boolean | no | Skip the cache and ask the sources again |

Response (202):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `stream_id` | string | yes | Opaque id of the run's event stream |
| `stream_url` | string | yes | Open this for the events (GET, text/event-stream) |
| `request_id` | string | yes | This call's request id, the ledger reference |
| `free_checks_remaining` | integer or null | no | Website free checks only: how many free checks the visitor has left today, after this one. Absent for calls made with an account's key or session. |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `402` Balance below the call's price (`insufficient_credits`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `413` The body is larger than 64 KiB (`invalid_request`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/streams" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"dns-lookup"}'
```

```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/streams", json={
    "tool": "dns-lookup",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/streams", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"tool":"dns-lookup"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/streams/{stream_id}

**Events of a streamed tool call.** Server-sent events for one run. Events, each with a JSON object in `data`:

- `started`: `{tool, target, request_id}`
- `section`: `{section, data}`, e.g. `section` `records` with `data` `{type, status, records}` for each DNS record type as soon as it is in
- `result` (last): the tool endpoint's 200 body plus `replayed`
- `error` (last): the error body, e.g. `source_unavailable` (not charged)

Send `Last-Event-ID` to resume after an event. Comments (`: keepalive`) keep quiet connections open. Streams expire 10 minutes after their last event.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `stream_id` | string | yes | `stream_id` from POST /v1/streams |

Errors:

- `404` No such job or stream, or it has expired (`not_found`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

```sh
curl "https://api.dnssuper.com/v1/streams/<stream_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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,
)
with client.stream("GET", "/v1/streams/<stream_id>", timeout=None) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/streams/<stream_id>`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const reader = response.body!.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(value);
}
```

### GET /v1/streams/{stream_id}/result

**Result of a streamed tool call.** The events a streamed call has published so far, as JSON, for clients whose event stream stalled or dropped. When the last event (`result` or `error`) is already there, the answer is immediate with `done: true`; otherwise it waits up to `wait` seconds for it. No API key needed (the stream id is the access). Never charges and never runs the call again.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `stream_id` | string | yes | `stream_id` from POST /v1/streams |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait` | integer | no | Seconds to wait for the last event |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `done` | boolean | yes | True when the last event is included |
| `events` | array of object | yes |  |
| `events.id` | string | yes | The event id (as the event stream's `id`) |
| `events.event` | string | yes | `started`, `section`, `result` or `error` |
| `events.data` | object | yes |  |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `404` No such job or stream, or it has expired (`not_found`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

```sh
curl "https://api.dnssuper.com/v1/streams/<stream_id>/result" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/streams/<stream_id>/result")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/streams/<stream_id>/result`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

## Shared reports

### GET /v1/shares

**Your shared links.** The account's shared links, newest first. `state=active` (default) lists links that still open; `all` adds expired and revoked ones (their snapshots are already gone). Page with `cursor`. Free.

No charge.

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no |  |
| `limit` | integer | no |  |
| `state` | "active" | "all" | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes |  |
| `items.id` | string | yes |  |
| `items.url` | string | yes |  |
| `items.tool` | string | yes |  |
| `items.tool_name` | string | yes |  |
| `items.target` | string | yes |  |
| `items.fetched_at` | string | yes |  |
| `items.created_at` | string | yes |  |
| `items.expires_at` | string | yes |  |
| `items.revoked_at` | string or null | yes |  |
| `items.has_password` | boolean | yes |  |
| `items.views` | integer | yes |  |
| `items.last_viewed_at` | string or null | yes |  |
| `items.state` | "active" | "expired" | "revoked" | yes |  |
| `next_cursor` | string or null | yes | Pass as `cursor` for the next page; null at the end |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/shares" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/shares")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/shares`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/shares

**Share a result.** Make a public link to a frozen copy of a result your account holds: a call's result (by its `X-Request-Id`, kept 24 hours) or a job row (kept 7 days). The link expires after `expires_in_days` (1 to 90, default 30) and can have a password. Sending the same `X-Request-Id` again returns the same link (200). Free; no usage is recorded.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | object | yes | Where the result comes from: a call's request id, or a job row. |
| `expires_in_days` | integer | no | Days until the link stops working (1 to 90) |
| `password` | string or null | no | Optional: visitors must enter it to open the link. Never stored in plain text |

Response (201):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `url` | string | yes |  |
| `tool` | string | yes |  |
| `tool_name` | string | yes |  |
| `target` | string | yes |  |
| `fetched_at` | string | yes |  |
| `created_at` | string | yes |  |
| `expires_at` | string | yes |  |
| `revoked_at` | string or null | yes |  |
| `has_password` | boolean | yes |  |
| `views` | integer | yes |  |
| `last_viewed_at` | string or null | yes |  |
| `state` | "active" | "expired" | "revoked" | yes |  |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` No API key or session, or an anonymous visitor (`unauthorized`, `sign_in_required`)
- `403` The account is suspended, has 1,000 active links, or a member tried to revoke someone else's link (`account_suspended`, `plan_limit`, `forbidden`)
- `404` No such result or shared report in this account (`not_found`)
- `429` Too many shared links made in the last hour (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/shares" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":{}}'
```

```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/shares", json={
    "source": {},
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/shares", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"source":{}}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/shares/{share_id}

**One shared link.** A shared link of this account, with its views and state. Free.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `share_id` | string | yes | The shared report's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `url` | string | yes |  |
| `tool` | string | yes |  |
| `tool_name` | string | yes |  |
| `target` | string | yes |  |
| `fetched_at` | string | yes |  |
| `created_at` | string | yes |  |
| `expires_at` | string | yes |  |
| `revoked_at` | string or null | yes |  |
| `has_password` | boolean | yes |  |
| `views` | integer | yes |  |
| `last_viewed_at` | string or null | yes |  |
| `state` | "active" | "expired" | "revoked" | yes |  |

Errors:

- `401` No API key or session, or an anonymous visitor (`unauthorized`, `sign_in_required`)
- `403` The account is suspended, has 1,000 active links, or a member tried to revoke someone else's link (`account_suspended`, `plan_limit`, `forbidden`)
- `404` No such result or shared report in this account (`not_found`)
- `429` Too many shared links made in the last hour (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/shares/<share_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/shares/<share_id>")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/shares/<share_id>`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### DELETE /v1/shares/{share_id}

**Revoke a shared link.** Stops the link working at once and deletes its snapshot. Members revoke their own links, owners any link of the account. Revoking twice is fine. Free.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `share_id` | string | yes | The shared report's ID |

Errors:

- `401` No API key or session, or an anonymous visitor (`unauthorized`, `sign_in_required`)
- `403` The account is suspended, has 1,000 active links, or a member tried to revoke someone else's link (`account_suspended`, `plan_limit`, `forbidden`)
- `404` No such result or shared report in this account (`not_found`)
- `429` Too many shared links made in the last hour (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X DELETE "https://api.dnssuper.com/v1/shares/<share_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.delete("/v1/shares/<share_id>")
response.raise_for_status()
print(response.status_code)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/shares/<share_id>`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.status);
```

## Monitors

### GET /v1/monitors

**List monitors.** Your account's monitors, oldest first, with the plan's limits.

No charge.

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no |  |
| `kind` | string or null | no |  |
| `health` | "ok" | "warn" | "fail" | "unknown" or null | no |  |
| `status` | "active" | "paused" | "limited" or null | no |  |
| `limit` | integer | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitors` | array of object | yes |  |
| `monitors.id` | string | yes |  |
| `monitors.kind` | string | yes |  |
| `monitors.target` | string | yes |  |
| `monitors.label` | string or null | yes |  |
| `monitors.interval` | integer | yes |  |
| `monitors.options` | object | yes |  |
| `monitors.rules` | object | yes |  |
| `monitors.paused` | boolean | yes |  |
| `monitors.limited` | string or null | yes | plan_kind or plan_count when your plan pauses it |
| `monitors.limited_note` | string or null | yes |  |
| `monitors.health` | "ok" | "warn" | "fail" | "unknown" | yes |  |
| `monitors.pending_confirmation` | boolean | yes |  |
| `monitors.last_run_at` | string or null | yes |  |
| `monitors.next_run_at` | string or null | yes |  |
| `monitors.last_event` | object or null | yes |  |
| `monitors.channel_ids` | array of string | yes |  |
| `monitors.created_at` | string | yes |  |
| `next_cursor` | string or null | yes |  |
| `limits` | object | yes |  |
| `limits.plan` | string | yes |  |
| `limits.monitors` | object | yes |  |
| `limits.lookalike_domains` | object | yes |  |
| `limits.kinds` | array of string | yes |  |
| `limits.min_interval` | object | yes |  |
| `limits.channels` | array of string | yes |  |

Errors:

- `400` Bad target or options, a selector that doesn't parse, or a jobs-only channel (`invalid_request`, `invalid_domain`, `invalid_url`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/monitors" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/monitors")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/monitors`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/monitors

**Create a monitor.** Start watching a domain or URL. The first check runs at once; checks are free. Send the same `X-Request-Id` again to get the monitor it already made (200).

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | "domain-expiry" | "ssl" | "dns" | "uptime" | "page-change" | "score-drop" | "lookalikes" | yes | What to watch |
| `target` | string | yes | A domain (domain-expiry, ssl, dns, lookalikes) or a URL (uptime, page-change, score-drop) |
| `interval` | integer or null | no | Seconds between checks; default: the kind's longest interval your plan allows |
| `options` | object | no | Options for this kind (see the docs) |
| `rules` | object | no |  |
| `channel_ids` | array of string or null | no | Alert channels; null: the account's default email channel |
| `label` | string or null | no |  |

Response (201):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `kind` | string | yes |  |
| `target` | string | yes |  |
| `label` | string or null | yes |  |
| `interval` | integer | yes |  |
| `options` | object | yes |  |
| `rules` | object | yes |  |
| `paused` | boolean | yes |  |
| `limited` | string or null | yes | plan_kind or plan_count when your plan pauses it |
| `limited_note` | string or null | yes |  |
| `health` | "ok" | "warn" | "fail" | "unknown" | yes |  |
| `pending_confirmation` | boolean | yes |  |
| `last_run_at` | string or null | yes |  |
| `next_run_at` | string or null | yes |  |
| `last_event` | object or null | yes |  |
| `channel_ids` | array of string | yes |  |
| `created_at` | string | yes |  |

Errors:

- `400` Bad target or options, a selector that doesn't parse, or a jobs-only channel (`invalid_request`, `invalid_domain`, `invalid_url`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `409` The same monitor exists, an unverified webhook, or no members to email (`duplicate_monitor`, `channel_unverified`, `no_members`)
- `429` Too many creates, changes or checks (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/monitors" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"domain-expiry","target":"example.com"}'
```

```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/monitors", json={
    "kind": "domain-expiry",
    "target": "example.com",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/monitors", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"kind":"domain-expiry","target":"example.com"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/monitors/{monitor_id}

**Get a monitor.**

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `kind` | string | yes |  |
| `target` | string | yes |  |
| `label` | string or null | yes |  |
| `interval` | integer | yes |  |
| `options` | object | yes |  |
| `rules` | object | yes |  |
| `paused` | boolean | yes |  |
| `limited` | string or null | yes | plan_kind or plan_count when your plan pauses it |
| `limited_note` | string or null | yes |  |
| `health` | "ok" | "warn" | "fail" | "unknown" | yes |  |
| `pending_confirmation` | boolean | yes |  |
| `last_run_at` | string or null | yes |  |
| `next_run_at` | string or null | yes |  |
| `last_event` | object or null | yes |  |
| `channel_ids` | array of string | yes |  |
| `created_at` | string | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/monitors/<monitor_id>")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/monitors/<monitor_id>`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### PATCH /v1/monitors/{monitor_id}

**Change a monitor.** Change the label, interval, options, alert rules, channels, or pause it. New options start a new baseline and count against the day's create limit.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string or null | no |  |
| `interval` | integer or null | no |  |
| `options` | object or null | no |  |
| `rules` | object or null | no |  |
| `channel_ids` | array of string or null | no |  |
| `paused` | boolean or null | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `kind` | string | yes |  |
| `target` | string | yes |  |
| `label` | string or null | yes |  |
| `interval` | integer | yes |  |
| `options` | object | yes |  |
| `rules` | object | yes |  |
| `paused` | boolean | yes |  |
| `limited` | string or null | yes | plan_kind or plan_count when your plan pauses it |
| `limited_note` | string or null | yes |  |
| `health` | "ok" | "warn" | "fail" | "unknown" | yes |  |
| `pending_confirmation` | boolean | yes |  |
| `last_run_at` | string or null | yes |  |
| `next_run_at` | string or null | yes |  |
| `last_event` | object or null | yes |  |
| `channel_ids` | array of string | yes |  |
| `created_at` | string | yes |  |

Errors:

- `400` Bad target or options, a selector that doesn't parse, or a jobs-only channel (`invalid_request`, `invalid_domain`, `invalid_url`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `409` The same monitor exists, an unverified webhook, or no members to email (`duplicate_monitor`, `channel_unverified`, `no_members`)
- `429` Too many creates, changes or checks (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X PATCH "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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.patch("/v1/monitors/<monitor_id>", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/monitors/<monitor_id>", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### DELETE /v1/monitors/{monitor_id}

**Delete a monitor.** Deletes the monitor with its runs and events. Its plan slot is free at once.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X DELETE "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.delete("/v1/monitors/<monitor_id>")
response.raise_for_status()
print(response.status_code)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/monitors/<monitor_id>`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.status);
```

### POST /v1/monitors/{monitor_id}/check

**Check now.** Run the monitor within about a minute. Free; 10 an hour per monitor and 60 an hour per account (lookalike monitors once a day). A check already running is left alone.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Response (202):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted` | boolean | no |  |
| `next_run_at` | string or null | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `429` Too many creates, changes or checks (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/monitors/<monitor_id>/check" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/monitors/<monitor_id>/check", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/monitors/<monitor_id>/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/monitors/{monitor_id}/events

**List a monitor's events.** Newest first.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no |  |
| `limit` | integer | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | array of object | yes |  |
| `events.id` | integer | yes |  |
| `events.kind` | string | yes |  |
| `events.severity` | string | yes |  |
| `events.title` | string | yes |  |
| `events.field` | string or null | yes |  |
| `events.finding_id` | string or null | yes |  |
| `events.before` | any | yes |  |
| `events.after` | any | yes |  |
| `events.occurred_at` | string | yes |  |
| `events.alerted` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |

Errors:

- `400` Bad target or options, a selector that doesn't parse, or a jobs-only channel (`invalid_request`, `invalid_domain`, `invalid_url`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>/events" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/monitors/<monitor_id>/events")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/monitors/<monitor_id>/events`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/monitors/{monitor_id}/uptime

**A monitor's uptime.** Daily checks and answers of an uptime monitor over the last 7, 30 or 90 days.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `monitor_id` | string | yes | The monitor's ID |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | integer | no | 7, 30 or 90 |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `uptime_pct` | number or null | yes |  |
| `days` | array of object | yes |  |
| `days.day` | string | yes |  |
| `days.checks` | integer | yes |  |
| `days.up` | integer | yes |  |
| `days.avg_ms` | integer or null | yes |  |
| `days.max_ms` | integer | yes |  |

Errors:

- `400` Bad target or options, a selector that doesn't parse, or a jobs-only channel (`invalid_request`, `invalid_domain`, `invalid_url`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not allowed by your plan, or an anonymous visitor (`plan_limit`, `plan_kind`, `interval_not_allowed`, `channel_not_allowed`, `sign_in_required`)
- `404` No such monitor or channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>/uptime" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/monitors/<monitor_id>/uptime")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/monitors/<monitor_id>/uptime`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

## Alert channels

### GET /v1/alert-channels

**List alert channels.**

No charge.

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channels` | array of object | yes |  |
| `channels.id` | string | yes |  |
| `channels.type` | string | yes |  |
| `channels.name` | string | yes |  |
| `channels.hint` | string or null | yes | A shortened form of the URL; never the full URL |
| `channels.recipients` | array of object | yes |  |
| `channels.digest` | boolean | yes |  |
| `channels.digest_hour` | integer | yes |  |
| `channels.status` | string | yes |  |
| `channels.paused_reason` | string or null | yes |  |
| `channels.limited` | boolean | yes |  |
| `channels.jobs_only` | boolean | yes |  |
| `channels.is_default` | boolean | yes |  |
| `channels.verified_at` | string or null | yes |  |
| `channels.failure_count` | integer | yes |  |
| `channels.last_success_at` | string or null | yes |  |
| `channels.created_at` | string | yes |  |
| `alert_delivery` | boolean | yes | False while alert delivery is off on this server |
| `bulk_unlocked` | boolean | no | True when the account may add a bulk completion (jobs_only) webhook |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/alert-channels" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/alert-channels")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/alert-channels`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/alert-channels

**Create an alert channel.** Email (to members of this account), a signed webhook, or a Slack incoming webhook. Webhooks start unverified: call /verify once your endpoint echoes the challenge. The signing secret is shown once.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "email" | "webhook" | "slack" | yes |  |
| `name` | string | yes |  |
| `url` | string or null | no |  |
| `recipients` | array of string or null | no |  |
| `digest` | boolean | no |  |
| `digest_hour` | integer | no |  |
| `jobs_only` | boolean | no |  |

Response (201):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `type` | string | yes |  |
| `name` | string | yes |  |
| `hint` | string or null | yes | A shortened form of the URL; never the full URL |
| `recipients` | array of object | yes |  |
| `recipients.user_id` | string | yes |  |
| `recipients.email` | string or null | yes | null when the user is no longer a member |
| `digest` | boolean | yes |  |
| `digest_hour` | integer | yes |  |
| `status` | string | yes |  |
| `paused_reason` | string or null | yes |  |
| `limited` | boolean | yes |  |
| `jobs_only` | boolean | yes |  |
| `is_default` | boolean | yes |  |
| `verified_at` | string or null | yes |  |
| `failure_count` | integer | yes |  |
| `last_success_at` | string or null | yes |  |
| `created_at` | string | yes |  |
| `signing_secret` | string or null | no | Webhooks only, shown once: verify our signatures with it |

Errors:

- `400` Bad URL or recipients (`invalid_request`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `409` 20 channels already, alert delivery off, or an unverified webhook (`channel_limit`, `alerts_off`, `channel_unverified`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/alert-channels" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"email","name":"<name>"}'
```

```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/alert-channels", json={
    "type": "email",
    "name": "<name>",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/alert-channels", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"type":"email","name":"<name>"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### PATCH /v1/alert-channels/{channel_id}

**Change an alert channel.** Rename, change the URL or recipients, the digest, or pause it. Resuming resets the failure count; a new webhook URL must be verified again.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string or null | no |  |
| `url` | string or null | no |  |
| `recipients` | array of string or null | no |  |
| `digest` | boolean or null | no |  |
| `digest_hour` | integer or null | no |  |
| `paused` | boolean or null | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `type` | string | yes |  |
| `name` | string | yes |  |
| `hint` | string or null | yes | A shortened form of the URL; never the full URL |
| `recipients` | array of object | yes |  |
| `recipients.user_id` | string | yes |  |
| `recipients.email` | string or null | yes | null when the user is no longer a member |
| `digest` | boolean | yes |  |
| `digest_hour` | integer | yes |  |
| `status` | string | yes |  |
| `paused_reason` | string or null | yes |  |
| `limited` | boolean | yes |  |
| `jobs_only` | boolean | yes |  |
| `is_default` | boolean | yes |  |
| `verified_at` | string or null | yes |  |
| `failure_count` | integer | yes |  |
| `last_success_at` | string or null | yes |  |
| `created_at` | string | yes |  |

Errors:

- `400` Bad URL or recipients (`invalid_request`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X PATCH "https://api.dnssuper.com/v1/alert-channels/<channel_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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.patch("/v1/alert-channels/<channel_id>", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/alert-channels/<channel_id>", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### DELETE /v1/alert-channels/{channel_id}

**Delete an alert channel.**

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X DELETE "https://api.dnssuper.com/v1/alert-channels/<channel_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.delete("/v1/alert-channels/<channel_id>")
response.raise_for_status()
print(response.status_code)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/alert-channels/<channel_id>`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.status);
```

### POST /v1/alert-channels/{channel_id}/verify

**Verify a webhook endpoint.** Sends one signed POST `{"type": "endpoint.verify", "challenge": "..."}`; the channel becomes active when the response body contains the challenge. 5 an hour per channel.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `verified` | boolean | yes |  |
| `status_class` | string or null | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `409` 20 channels already, alert delivery off, or an unverified webhook (`channel_limit`, `alerts_off`, `channel_unverified`)
- `429` Too many test sends or verifications (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/alert-channels/<channel_id>/verify" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/alert-channels/<channel_id>/verify", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/alert-channels/<channel_id>/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/alert-channels/{channel_id}/test

**Send a test alert.** Queues one test delivery. 5 an hour per channel and 20 an hour per account.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Response (202):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `kind` | string | yes |  |
| `status` | string | yes |  |
| `attempts` | integer | yes |  |
| `status_class` | string or null | yes | 2xx, 3xx, 4xx or 5xx; never the exact code |
| `error_code` | string or null | yes |  |
| `created_at` | string | yes |  |
| `sent_at` | string or null | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `409` 20 channels already, alert delivery off, or an unverified webhook (`channel_limit`, `alerts_off`, `channel_unverified`)
- `429` Too many test sends or verifications (`rate_limited`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/alert-channels/<channel_id>/test" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/alert-channels/<channel_id>/test", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/alert-channels/<channel_id>/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/alert-channels/{channel_id}/rotate-secret

**Rotate a webhook's signing secret.** The new secret is shown once; requests are signed with it from now on.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `signing_secret` | string | yes |  |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/alert-channels/<channel_id>/rotate-secret" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/alert-channels/<channel_id>/rotate-secret", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/alert-channels/<channel_id>/rotate-secret", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/alert-channels/{channel_id}/deliveries

**A channel's delivery log.** Newest first; the HTTP status class only (2xx, 3xx, 4xx, 5xx).

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `channel_id` | string | yes | The alert channel's ID |

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no |  |
| `limit` | integer | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `deliveries` | array of object | yes |  |
| `deliveries.id` | string | yes |  |
| `deliveries.kind` | string | yes |  |
| `deliveries.status` | string | yes |  |
| `deliveries.attempts` | integer | yes |  |
| `deliveries.status_class` | string or null | yes | 2xx, 3xx, 4xx or 5xx; never the exact code |
| `deliveries.error_code` | string or null | yes |  |
| `deliveries.created_at` | string | yes |  |
| `deliveries.sent_at` | string or null | yes |  |
| `next_cursor` | string or null | yes |  |

Errors:

- `400` Bad URL or recipients (`invalid_request`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Not in your plan, or an anonymous visitor (`channel_not_allowed`, `sign_in_required`)
- `404` No such channel in this account (`not_found`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/alert-channels/<channel_id>/deliveries" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/alert-channels/<channel_id>/deliveries")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/alert-channels/<channel_id>/deliveries`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

## Calendar feeds

### GET /v1/calendar-feeds

**Calendar feed state.** Whether the account has an expiry calendar feed, when it was made and last fetched, and how many domain-expiry monitors it lists. Never returns the URL.

No charge.

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `active` | boolean | yes | Whether the account has a feed URL that works |
| `created_at` | string or null | yes | When the current URL was made |
| `last_fetched_at` | string or null | yes | When a calendar app last fetched it (updated at most hourly) |
| `domains` | integer | yes | Domain-expiry monitors the calendar lists |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/calendar-feeds" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/calendar-feeds")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/calendar-feeds`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/calendar-feeds

**Make or rotate the calendar feed.** Make the account's expiry calendar feed URL, or replace it: the old URL stops working at once. The URL is returned only this time. Owners only (or a key the owner made). Free.

No charge.

Response (201):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The feed URL. Shown once: we keep only a hash of it. Whoever has it, including the calendar app's provider, sees the monitored domains and their dates. |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X POST "https://api.dnssuper.com/v1/calendar-feeds" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```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/calendar-feeds", json={})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/calendar-feeds", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### DELETE /v1/calendar-feeds

**Revoke the calendar feed.** Turn the feed URL off. Idempotent. Owners only (or a key the owner made).

No charge.

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `500` Unexpected error (`internal_error`)

```sh
curl -X DELETE "https://api.dnssuper.com/v1/calendar-feeds" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.delete("/v1/calendar-feeds")
response.raise_for_status()
print(response.status_code)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/calendar-feeds`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.status);
```

### GET /v1/calendar-feeds/download

**Download the monitored-domains calendar.** The calendar the feed serves, as a one-off `.ics` download: one all-day event per domain-expiry monitor on its expiry date, with reminders 30 and 7 days before. Free.

No charge.

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/calendar-feeds/download" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/calendar-feeds/download")
response.raise_for_status()
print(response.text)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/calendar-feeds/download`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(await response.text());
```

## Exports

### GET /v1/exports

**Your PDF exports.** The account's PDF exports, newest first, with their status. No charge.

No charge.

Query parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string or null | no |  |
| `limit` | integer | no |  |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes |  |
| `items.id` | string | yes |  |
| `items.format` | string | yes |  |
| `items.status` | "queued" | "running" | "done" | "failed" | yes |  |
| `items.source_kind` | string | yes |  |
| `items.white_label` | boolean | yes |  |
| `items.filename` | string | yes |  |
| `items.pages` | integer or null | yes |  |
| `items.size_bytes` | integer or null | yes |  |
| `items.created_at` | string | yes |  |
| `items.finished_at` | string or null | yes |  |
| `items.expires_at` | string | yes |  |
| `items.error` | object or null | yes |  |
| `items.file_url` | string or null | no | Where to download the PDF once it is done (the same auth) |
| `next_cursor` | string or null | yes |  |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/exports" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/exports")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/exports`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### POST /v1/exports

**Export a result.** Export a result you hold: a call (by its `X-Request-Id`, kept 24 hours), a job or one of its rows (7 days), a compare, or a monitor's history. JSON, CSV and iCalendar files stream back at once and are never stored. A PDF is made in the background: the answer is 202 with the export, whose `status` becomes `done` within a minute or two; download it from `file_url` (kept 24 hours). Sending the same `X-Request-Id` again returns the same export. Formats follow the tool: registration lookups export JSON and CSV only, iCalendar only from expiry calendars. On the Agency plan PDFs carry your branding. Free; at most 60 exports and 5 PDFs (20 on paid plans) an hour.

No charge.

Request body:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | any | yes | What to export: a call, a job, a compare or a monitor |
| `format` | "json" | "csv" | "pdf" | "ics" | yes |  |
| `branding` | "auto" | "none" | no | auto: a white-label PDF when your plan allows it and you saved branding |

Errors:

- `400` Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)
- `503` Too many open event streams on this server, the checked site is getting too many checks, or the browser or link checker is busy; try again after the seconds in the Retry-After header (`busy`, `site_busy`, `browser_busy`, `crawl_busy`). Not charged

```sh
curl -X POST "https://api.dnssuper.com/v1/exports" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"<source>","format":"json"}'
```

```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/exports", json={
    "source": "<source>",
    "format": "json",
})
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch("https://api.dnssuper.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"source":"<source>","format":"json"}),
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### GET /v1/exports/{export_id}

**A PDF export.** One PDF export and its status. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `export_id` | string | yes | The export's ID |

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `format` | string | yes |  |
| `status` | "queued" | "running" | "done" | "failed" | yes |  |
| `source_kind` | string | yes |  |
| `white_label` | boolean | yes |  |
| `filename` | string | yes |  |
| `pages` | integer or null | yes |  |
| `size_bytes` | integer or null | yes |  |
| `created_at` | string | yes |  |
| `finished_at` | string or null | yes |  |
| `expires_at` | string | yes |  |
| `error` | object or null | yes |  |
| `file_url` | string or null | no | Where to download the PDF once it is done (the same auth) |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/exports/<export_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/exports/<export_id>")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/exports/<export_id>`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

### DELETE /v1/exports/{export_id}

**Delete a PDF export.** Delete the export and its file now. Deleting twice is fine. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `export_id` | string | yes | The export's ID |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl -X DELETE "https://api.dnssuper.com/v1/exports/<export_id>" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.delete("/v1/exports/<export_id>")
response.raise_for_status()
print(response.status_code)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/exports/<export_id>`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.status);
```

### GET /v1/exports/{export_id}/file

**Download a PDF export.** The PDF of a finished export, kept 24 hours. No charge.

No charge.

Path parameters:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `export_id` | string | yes | The export's ID |

Errors:

- `401` Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
- `403` Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
- `404` No such job or stream, or it has expired (`not_found`)
- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
- `500` Unexpected error (`internal_error`)

```sh
curl "https://api.dnssuper.com/v1/exports/<export_id>/file" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/exports/<export_id>/file")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/exports/<export_id>/file`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```

## Status

### GET /v1/status

**Service status.** The current state of each part of DNS Super, 90 days of daily uptime, the last TLD canary run and open and recent incidents. Public: no key, no charge. Cached for 30 seconds.

No charge. No API key needed.

Response (200):

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `generated_at` | string | yes |  |
| `overall` | "operational" | "degraded" | "outage" | "maintenance" | "unknown" | yes |  |
| `components` | array of object | yes |  |
| `components.id` | "web" | "api" | "mcp" | "jobs" | "monitoring" | "browser" | "dns" | "registration" | "email" | "payments" | yes |  |
| `components.name` | string | yes |  |
| `components.state` | "operational" | "degraded" | "outage" | "maintenance" | "unknown" | yes |  |
| `components.since` | string or null | no |  |
| `components.detail_code` | "probe_failed" | "slow_responses" | "not_ready" | "error_rate" | "no_replica" | "heartbeat_stale" | "queue_backlog" | "schedule_lag" | "capacity_limited" | "dns_slow" | "dns_failures" | "source_delays" | "canary_failures" | "send_failures" | "webhook_errors" | "api_unreachable" | "planned_maintenance" or null | no |  |
| `components.uptime_90d` | number or null | no | Percent of sampled minutes without an outage, last 90 days |
| `components.days` | array of object | no |  |
| `registration` | object | yes |  |
| `registration.checked_at` | string or null | no |  |
| `registration.tlds_total` | integer | no |  |
| `registration.tlds_ok` | integer | no |  |
| `registration.failing_tlds` | array of string | no |  |
| `incidents` | object | yes |  |
| `incidents.open` | array of object | no |  |
| `incidents.recent` | array of object | no | Resolved in 14 days |

Errors:

- `429` Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged

```sh
curl "https://api.dnssuper.com/v1/status" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"
```

```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.get("/v1/status")
response.raise_for_status()
result = response.json()
print(result)
```

```typescript
const response = await fetch(`https://api.dnssuper.com/v1/status`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result);
```
