API reference
Every endpoint that isn't a tool. Each check has its own page in the tool reference. Send your API key as Authorization: Bearer <key> on every call unless it says otherwise. The whole spec is at /docs/openapi.json. Python and TypeScript samples for every endpoint are in the Markdown version.
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 | Description |
|---|---|---|
| account (required) | object | |
| account.id (required) | string | |
| account.email (required) | string | |
| account.plan (required) | string | |
| account.status (required) | "active" | "suspended" | |
| credits (required) | object | |
| credits.balance (required) | integer | |
| recent_usage (required) | array of object | Last 20 usage events, newest first |
| recent_usage.time (required) | string | |
| recent_usage.tool (required) | string | |
| recent_usage.target (required) | string | |
| recent_usage.credits (required) | integer | |
| recent_usage.cached (required) | boolean | |
| recent_usage.status (required) | "ok" | "partial" | "error" |
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`)
curl "https://api.dnssuper.com/v1/account" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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
curl "https://api.dnssuper.com/v1/account/events" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| cursor | string or null | `next_cursor` from the previous page |
| limit | integer | Jobs per page |
| status | "unfinished" | "finished" | "all" | Which jobs to list |
| kind | "tool" | "bulk" | "all" | Tool jobs, bulk checks or both |
Response (200)
| Name | Type | Description |
|---|---|---|
| items (required) | array of object | |
| items.id (required) | string | |
| items.tool (required) | string | |
| items.status (required) | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | |
| items.total (required) | integer | Rows in the job |
| items.done (required) | integer | Rows with a result (charged) |
| items.failed (required) | integer | Rows whose sources didn't answer (not charged) |
| items.credits_reserved (required) | integer | Credits held when the job was submitted |
| items.credits_used (required) | integer | Credits charged so far; the rest of the reservation returns when it ends |
| items.created_at (required) | string | |
| items.started_at (required) | string or null | |
| items.finished_at (required) | string or null | |
| items.progress | object or null | The running row's own progress, such as pages crawled; null when none |
| items.label | string or null | The label given when it was submitted |
| items.bulk | boolean | True for a bulk check |
| items.estimated_remaining_s | integer or null | 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 (required) | string or null | 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`)
curl "https://api.dnssuper.com/v1/jobs" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| job_id (required) | string | The job's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| tool (required) | string | |
| status (required) | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | |
| total (required) | integer | Rows in the job |
| done (required) | integer | Rows with a result (charged) |
| failed (required) | integer | Rows whose sources didn't answer (not charged) |
| credits_reserved (required) | integer | Credits held when the job was submitted |
| credits_used (required) | integer | Credits charged so far; the rest of the reservation returns when it ends |
| created_at (required) | string | |
| started_at (required) | string or null | |
| finished_at (required) | string or null | |
| progress | object or null | The running row's own progress, such as pages crawled; null when none |
| label | string or null | The label given when it was submitted |
| bulk | boolean | True for a bulk check |
| estimated_remaining_s | integer or null | 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`)
curl "https://api.dnssuper.com/v1/jobs/<job_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| job_id (required) | string | The job's ID |
Query parameters
| Name | Type | Description |
|---|---|---|
| after | integer | Return rows after this row number |
| limit | integer | Rows per page |
Response (200)
| Name | Type | Description |
|---|---|---|
| items (required) | array of object | |
| items.row (required) | integer | Row number, starting at 1 |
| items.target (required) | string | |
| items.status (required) | "queued" | "done" | "failed" | "skipped" | |
| items.cached (required) | boolean | |
| items.credits (required) | integer | |
| items.error (required) | object or null | |
| items.result (required) | object or null | The row's result envelope; null until it is done, and after 7 days |
| next_after (required) | integer or null | 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`)
curl "https://api.dnssuper.com/v1/jobs/<job_id>/items" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| job_id (required) | string | The job's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| tool (required) | string | |
| status (required) | "queued" | "running" | "cancelling" | "done" | "cancelled" | "failed" | |
| total (required) | integer | Rows in the job |
| done (required) | integer | Rows with a result (charged) |
| failed (required) | integer | Rows whose sources didn't answer (not charged) |
| credits_reserved (required) | integer | Credits held when the job was submitted |
| credits_used (required) | integer | Credits charged so far; the rest of the reservation returns when it ends |
| created_at (required) | string | |
| started_at (required) | string or null | |
| finished_at (required) | string or null | |
| progress | object or null | The running row's own progress, such as pages crawled; null when none |
| label | string or null | The label given when it was submitted |
| bulk | boolean | True for a bulk check |
| estimated_remaining_s | integer or null | 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`)
curl -X POST "https://api.dnssuper.com/v1/jobs/<job_id>/cancel" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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 | Description |
|---|---|---|
| job_id (required) | string | 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
curl "https://api.dnssuper.com/v1/jobs/<job_id>/events" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| tool (required) | string | Registry id of the tool |
Query parameters
| Name | Type | Description |
|---|---|---|
| dry_run | boolean | Show the rows, errors, credits and time without starting the job |
| skip_invalid | boolean | Run only the valid rows instead of refusing the job |
Request body
| Name | Type | Description |
|---|---|---|
| targets | array of any or null | Names to check, one per row |
| rows | array of object or null | Rows of the tool's own input properties |
| csv | string or null | The text of a CSV file: a header naming the tool's inputs, one row per check |
| options | object | Job-wide parameters for every row: `fresh`, variant and per-unit options, and any shared tool parameter |
| label | string or null | Your name for the job |
| notify | object or null | Send a notice to this alert channel when the job finishes |
| check_ownership | boolean | Dry runs only: also check the TXT ownership records (subdomain takeover) |
Response (200)
| Name | Type | Description |
|---|---|---|
| tool (required) | string | |
| rows (required) | integer | Rows sent |
| unique (required) | integer | Valid rows that would run after removing duplicates |
| duplicates_removed (required) | integer | |
| invalid (required) | integer | Rows with an error |
| errors (required) | array of object | The first 100 row errors |
| errors.row (required) | integer | CSV line (1-based) or position in the list |
| errors.column (required) | string or null | |
| errors.message (required) | string | |
| columns (required) | array of string | The input each column was read as |
| preview (required) | array of object | The first 5 valid rows |
| preview.row (required) | integer | |
| preview.target (required) | string | |
| preview.options (required) | object | |
| limit (required) | integer | The most rows one bulk check with this tool may have |
| credits (required) | integer | Credits the job would hold when it starts |
| balance (required) | integer | Your balance now |
| estimated_max_s (required) | integer | The longest the job could take, if every row is as slow as it can be |
| unverified (required) | array of string | Domains still needing their TXT ownership record (at most 20) |
| records | array of object | The TXT record to publish for each of them |
| records.domain (required) | string | |
| records.record_name (required) | string | |
| records.record_value (required) | string | |
| verification_checked (required) | boolean | 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`)
curl -X POST "https://api.dnssuper.com/v1/bulk/<tool>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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 | Description |
|---|---|---|
| domain (required) | string |
Response (200)
| Name | Type | Description |
|---|---|---|
| domain (required) | string | The registrable domain the record proves |
| record_name (required) | string | Where to publish the TXT record |
| record_value (required) | string | 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`)
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"}'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 | Description |
|---|---|---|
| domain (required) | string |
Response (200)
| Name | Type | Description |
|---|---|---|
| domain (required) | string | |
| verified (required) | boolean | 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`)
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"}'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 | Description |
|---|---|---|
| tool (required) | string | Registry id of the tool |
| input | object | The tool's parameters, as for its own endpoint |
| fresh | boolean | Skip the cache and ask the sources again |
Response (202)
| Name | Type | Description |
|---|---|---|
| stream_id (required) | string | Opaque id of the run's event stream |
| stream_url (required) | string | Open this for the events (GET, text/event-stream) |
| request_id (required) | string | This call's request id, the ledger reference |
| free_checks_remaining | integer or null | 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`)
curl -X POST "https://api.dnssuper.com/v1/streams" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"dns-lookup"}'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 | Description |
|---|---|---|
| stream_id (required) | string | `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
curl "https://api.dnssuper.com/v1/streams/<stream_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| stream_id (required) | string | `stream_id` from POST /v1/streams |
Query parameters
| Name | Type | Description |
|---|---|---|
| wait | integer | Seconds to wait for the last event |
Response (200)
| Name | Type | Description |
|---|---|---|
| done (required) | boolean | True when the last event is included |
| events (required) | array of object | |
| events.id (required) | string | The event id (as the event stream's `id`) |
| events.event (required) | string | `started`, `section`, `result` or `error` |
| events.data (required) | object |
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
curl "https://api.dnssuper.com/v1/streams/<stream_id>/result" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| cursor | string or null | |
| limit | integer | |
| state | "active" | "all" |
Response (200)
| Name | Type | Description |
|---|---|---|
| items (required) | array of object | |
| items.id (required) | string | |
| items.url (required) | string | |
| items.tool (required) | string | |
| items.tool_name (required) | string | |
| items.target (required) | string | |
| items.fetched_at (required) | string | |
| items.created_at (required) | string | |
| items.expires_at (required) | string | |
| items.revoked_at (required) | string or null | |
| items.has_password (required) | boolean | |
| items.views (required) | integer | |
| items.last_viewed_at (required) | string or null | |
| items.state (required) | "active" | "expired" | "revoked" | |
| next_cursor (required) | string or null | 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`)
curl "https://api.dnssuper.com/v1/shares" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| source (required) | object | Where the result comes from: a call's request id, or a job row. |
| expires_in_days | integer | Days until the link stops working (1 to 90) |
| password | string or null | Optional: visitors must enter it to open the link. Never stored in plain text |
Response (201)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| url (required) | string | |
| tool (required) | string | |
| tool_name (required) | string | |
| target (required) | string | |
| fetched_at (required) | string | |
| created_at (required) | string | |
| expires_at (required) | string | |
| revoked_at (required) | string or null | |
| has_password (required) | boolean | |
| views (required) | integer | |
| last_viewed_at (required) | string or null | |
| state (required) | "active" | "expired" | "revoked" |
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`)
curl -X POST "https://api.dnssuper.com/v1/shares" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source":{}}'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 | Description |
|---|---|---|
| share_id (required) | string | The shared report's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| url (required) | string | |
| tool (required) | string | |
| tool_name (required) | string | |
| target (required) | string | |
| fetched_at (required) | string | |
| created_at (required) | string | |
| expires_at (required) | string | |
| revoked_at (required) | string or null | |
| has_password (required) | boolean | |
| views (required) | integer | |
| last_viewed_at (required) | string or null | |
| state (required) | "active" | "expired" | "revoked" |
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`)
curl "https://api.dnssuper.com/v1/shares/<share_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| share_id (required) | string | 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`)
curl -X DELETE "https://api.dnssuper.com/v1/shares/<share_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"Monitors
GET/v1/monitors
List monitors
Your account's monitors, oldest first, with the plan's limits.
No charge.
Query parameters
| Name | Type | Description |
|---|---|---|
| cursor | string or null | |
| kind | string or null | |
| health | "ok" | "warn" | "fail" | "unknown" or null | |
| status | "active" | "paused" | "limited" or null | |
| limit | integer |
Response (200)
| Name | Type | Description |
|---|---|---|
| monitors (required) | array of object | |
| monitors.id (required) | string | |
| monitors.kind (required) | string | |
| monitors.target (required) | string | |
| monitors.label (required) | string or null | |
| monitors.interval (required) | integer | |
| monitors.options (required) | object | |
| monitors.rules (required) | object | |
| monitors.paused (required) | boolean | |
| monitors.limited (required) | string or null | plan_kind or plan_count when your plan pauses it |
| monitors.limited_note (required) | string or null | |
| monitors.health (required) | "ok" | "warn" | "fail" | "unknown" | |
| monitors.pending_confirmation (required) | boolean | |
| monitors.last_run_at (required) | string or null | |
| monitors.next_run_at (required) | string or null | |
| monitors.last_event (required) | object or null | |
| monitors.channel_ids (required) | array of string | |
| monitors.created_at (required) | string | |
| next_cursor (required) | string or null | |
| limits (required) | object | |
| limits.plan (required) | string | |
| limits.monitors (required) | object | |
| limits.lookalike_domains (required) | object | |
| limits.kinds (required) | array of string | |
| limits.min_interval (required) | object | |
| limits.channels (required) | array of string |
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`)
curl "https://api.dnssuper.com/v1/monitors" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| kind (required) | "domain-expiry" | "ssl" | "dns" | "uptime" | "page-change" | "score-drop" | "lookalikes" | What to watch |
| target (required) | string | A domain (domain-expiry, ssl, dns, lookalikes) or a URL (uptime, page-change, score-drop) |
| interval | integer or null | Seconds between checks; default: the kind's longest interval your plan allows |
| options | object | Options for this kind (see the docs) |
| rules | object | |
| channel_ids | array of string or null | Alert channels; null: the account's default email channel |
| label | string or null |
Response (201)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| kind (required) | string | |
| target (required) | string | |
| label (required) | string or null | |
| interval (required) | integer | |
| options (required) | object | |
| rules (required) | object | |
| paused (required) | boolean | |
| limited (required) | string or null | plan_kind or plan_count when your plan pauses it |
| limited_note (required) | string or null | |
| health (required) | "ok" | "warn" | "fail" | "unknown" | |
| pending_confirmation (required) | boolean | |
| last_run_at (required) | string or null | |
| next_run_at (required) | string or null | |
| last_event (required) | object or null | |
| channel_ids (required) | array of string | |
| created_at (required) | string |
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`)
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"}'GET/v1/monitors/{monitor_id}
Get a monitor
No charge.
Path parameters
| Name | Type | Description |
|---|---|---|
| monitor_id (required) | string | The monitor's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| kind (required) | string | |
| target (required) | string | |
| label (required) | string or null | |
| interval (required) | integer | |
| options (required) | object | |
| rules (required) | object | |
| paused (required) | boolean | |
| limited (required) | string or null | plan_kind or plan_count when your plan pauses it |
| limited_note (required) | string or null | |
| health (required) | "ok" | "warn" | "fail" | "unknown" | |
| pending_confirmation (required) | boolean | |
| last_run_at (required) | string or null | |
| next_run_at (required) | string or null | |
| last_event (required) | object or null | |
| channel_ids (required) | array of string | |
| created_at (required) | string |
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`)
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| monitor_id (required) | string | The monitor's ID |
Request body
| Name | Type | Description |
|---|---|---|
| label | string or null | |
| interval | integer or null | |
| options | object or null | |
| rules | object or null | |
| channel_ids | array of string or null | |
| paused | boolean or null |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| kind (required) | string | |
| target (required) | string | |
| label (required) | string or null | |
| interval (required) | integer | |
| options (required) | object | |
| rules (required) | object | |
| paused (required) | boolean | |
| limited (required) | string or null | plan_kind or plan_count when your plan pauses it |
| limited_note (required) | string or null | |
| health (required) | "ok" | "warn" | "fail" | "unknown" | |
| pending_confirmation (required) | boolean | |
| last_run_at (required) | string or null | |
| next_run_at (required) | string or null | |
| last_event (required) | object or null | |
| channel_ids (required) | array of string | |
| created_at (required) | string |
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`)
curl -X PATCH "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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 | Description |
|---|---|---|
| monitor_id (required) | string | 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`)
curl -X DELETE "https://api.dnssuper.com/v1/monitors/<monitor_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| monitor_id (required) | string | The monitor's ID |
Response (202)
| Name | Type | Description |
|---|---|---|
| accepted | boolean | |
| next_run_at (required) | string or null |
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`)
curl -X POST "https://api.dnssuper.com/v1/monitors/<monitor_id>/check" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'GET/v1/monitors/{monitor_id}/events
List a monitor's events
Newest first.
No charge.
Path parameters
| Name | Type | Description |
|---|---|---|
| monitor_id (required) | string | The monitor's ID |
Query parameters
| Name | Type | Description |
|---|---|---|
| cursor | string or null | |
| limit | integer |
Response (200)
| Name | Type | Description |
|---|---|---|
| events (required) | array of object | |
| events.id (required) | integer | |
| events.kind (required) | string | |
| events.severity (required) | string | |
| events.title (required) | string | |
| events.field (required) | string or null | |
| events.finding_id (required) | string or null | |
| events.before (required) | any | |
| events.after (required) | any | |
| events.occurred_at (required) | string | |
| events.alerted (required) | boolean | |
| next_cursor (required) | string or null |
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`)
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>/events" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| monitor_id (required) | string | The monitor's ID |
Query parameters
| Name | Type | Description |
|---|---|---|
| days | integer | 7, 30 or 90 |
Response (200)
| Name | Type | Description |
|---|---|---|
| uptime_pct (required) | number or null | |
| days (required) | array of object | |
| days.day (required) | string | |
| days.checks (required) | integer | |
| days.up (required) | integer | |
| days.avg_ms (required) | integer or null | |
| days.max_ms (required) | integer |
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`)
curl "https://api.dnssuper.com/v1/monitors/<monitor_id>/uptime" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"Alert channels
GET/v1/alert-channels
List alert channels
No charge.
Response (200)
| Name | Type | Description |
|---|---|---|
| channels (required) | array of object | |
| channels.id (required) | string | |
| channels.type (required) | string | |
| channels.name (required) | string | |
| channels.hint (required) | string or null | A shortened form of the URL; never the full URL |
| channels.recipients (required) | array of object | |
| channels.digest (required) | boolean | |
| channels.digest_hour (required) | integer | |
| channels.status (required) | string | |
| channels.paused_reason (required) | string or null | |
| channels.limited (required) | boolean | |
| channels.jobs_only (required) | boolean | |
| channels.is_default (required) | boolean | |
| channels.verified_at (required) | string or null | |
| channels.failure_count (required) | integer | |
| channels.last_success_at (required) | string or null | |
| channels.created_at (required) | string | |
| alert_delivery (required) | boolean | False while alert delivery is off on this server |
| bulk_unlocked | boolean | 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`)
curl "https://api.dnssuper.com/v1/alert-channels" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| type (required) | "email" | "webhook" | "slack" | |
| name (required) | string | |
| url | string or null | |
| recipients | array of string or null | |
| digest | boolean | |
| digest_hour | integer | |
| jobs_only | boolean |
Response (201)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| type (required) | string | |
| name (required) | string | |
| hint (required) | string or null | A shortened form of the URL; never the full URL |
| recipients (required) | array of object | |
| recipients.user_id (required) | string | |
| recipients.email (required) | string or null | null when the user is no longer a member |
| digest (required) | boolean | |
| digest_hour (required) | integer | |
| status (required) | string | |
| paused_reason (required) | string or null | |
| limited (required) | boolean | |
| jobs_only (required) | boolean | |
| is_default (required) | boolean | |
| verified_at (required) | string or null | |
| failure_count (required) | integer | |
| last_success_at (required) | string or null | |
| created_at (required) | string | |
| signing_secret | string or null | 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`)
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>"}'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 | Description |
|---|---|---|
| channel_id (required) | string | The alert channel's ID |
Request body
| Name | Type | Description |
|---|---|---|
| name | string or null | |
| url | string or null | |
| recipients | array of string or null | |
| digest | boolean or null | |
| digest_hour | integer or null | |
| paused | boolean or null |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| type (required) | string | |
| name (required) | string | |
| hint (required) | string or null | A shortened form of the URL; never the full URL |
| recipients (required) | array of object | |
| recipients.user_id (required) | string | |
| recipients.email (required) | string or null | null when the user is no longer a member |
| digest (required) | boolean | |
| digest_hour (required) | integer | |
| status (required) | string | |
| paused_reason (required) | string or null | |
| limited (required) | boolean | |
| jobs_only (required) | boolean | |
| is_default (required) | boolean | |
| verified_at (required) | string or null | |
| failure_count (required) | integer | |
| last_success_at (required) | string or null | |
| created_at (required) | string |
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`)
curl -X PATCH "https://api.dnssuper.com/v1/alert-channels/<channel_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'DELETE/v1/alert-channels/{channel_id}
Delete an alert channel
No charge.
Path parameters
| Name | Type | Description |
|---|---|---|
| channel_id (required) | string | 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`)
curl -X DELETE "https://api.dnssuper.com/v1/alert-channels/<channel_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| channel_id (required) | string | The alert channel's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| verified (required) | boolean | |
| status_class (required) | string or null |
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`)
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 '{}'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 | Description |
|---|---|---|
| channel_id (required) | string | The alert channel's ID |
Response (202)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| kind (required) | string | |
| status (required) | string | |
| attempts (required) | integer | |
| status_class (required) | string or null | 2xx, 3xx, 4xx or 5xx; never the exact code |
| error_code (required) | string or null | |
| created_at (required) | string | |
| sent_at (required) | string or null |
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`)
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 '{}'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 | Description |
|---|---|---|
| channel_id (required) | string | The alert channel's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| signing_secret (required) | string |
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`)
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 '{}'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 | Description |
|---|---|---|
| channel_id (required) | string | The alert channel's ID |
Query parameters
| Name | Type | Description |
|---|---|---|
| cursor | string or null | |
| limit | integer |
Response (200)
| Name | Type | Description |
|---|---|---|
| deliveries (required) | array of object | |
| deliveries.id (required) | string | |
| deliveries.kind (required) | string | |
| deliveries.status (required) | string | |
| deliveries.attempts (required) | integer | |
| deliveries.status_class (required) | string or null | 2xx, 3xx, 4xx or 5xx; never the exact code |
| deliveries.error_code (required) | string or null | |
| deliveries.created_at (required) | string | |
| deliveries.sent_at (required) | string or null | |
| next_cursor (required) | string or null |
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`)
curl "https://api.dnssuper.com/v1/alert-channels/<channel_id>/deliveries" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| active (required) | boolean | Whether the account has a feed URL that works |
| created_at (required) | string or null | When the current URL was made |
| last_fetched_at (required) | string or null | When a calendar app last fetched it (updated at most hourly) |
| domains (required) | integer | 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`)
curl "https://api.dnssuper.com/v1/calendar-feeds" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| url (required) | string | 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`)
curl -X POST "https://api.dnssuper.com/v1/calendar-feeds" \
-H "Authorization: Bearer $DNSSUPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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`)
curl -X DELETE "https://api.dnssuper.com/v1/calendar-feeds" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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`)
curl "https://api.dnssuper.com/v1/calendar-feeds/download" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| cursor | string or null | |
| limit | integer |
Response (200)
| Name | Type | Description |
|---|---|---|
| items (required) | array of object | |
| items.id (required) | string | |
| items.format (required) | string | |
| items.status (required) | "queued" | "running" | "done" | "failed" | |
| items.source_kind (required) | string | |
| items.white_label (required) | boolean | |
| items.filename (required) | string | |
| items.pages (required) | integer or null | |
| items.size_bytes (required) | integer or null | |
| items.created_at (required) | string | |
| items.finished_at (required) | string or null | |
| items.expires_at (required) | string | |
| items.error (required) | object or null | |
| items.file_url | string or null | Where to download the PDF once it is done (the same auth) |
| next_cursor (required) | string or null |
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`)
curl "https://api.dnssuper.com/v1/exports" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| source (required) | any | What to export: a call, a job, a compare or a monitor |
| format (required) | "json" | "csv" | "pdf" | "ics" | |
| branding | "auto" | "none" | 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
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"}'GET/v1/exports/{export_id}
A PDF export
One PDF export and its status. No charge.
No charge.
Path parameters
| Name | Type | Description |
|---|---|---|
| export_id (required) | string | The export's ID |
Response (200)
| Name | Type | Description |
|---|---|---|
| id (required) | string | |
| format (required) | string | |
| status (required) | "queued" | "running" | "done" | "failed" | |
| source_kind (required) | string | |
| white_label (required) | boolean | |
| filename (required) | string | |
| pages (required) | integer or null | |
| size_bytes (required) | integer or null | |
| created_at (required) | string | |
| finished_at (required) | string or null | |
| expires_at (required) | string | |
| error (required) | object or null | |
| file_url | string or null | 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`)
curl "https://api.dnssuper.com/v1/exports/<export_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| export_id (required) | string | 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`)
curl -X DELETE "https://api.dnssuper.com/v1/exports/<export_id>" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| export_id (required) | string | 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`)
curl "https://api.dnssuper.com/v1/exports/<export_id>/file" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"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 | Description |
|---|---|---|
| generated_at (required) | string | |
| overall (required) | "operational" | "degraded" | "outage" | "maintenance" | "unknown" | |
| components (required) | array of object | |
| components.id (required) | "web" | "api" | "mcp" | "jobs" | "monitoring" | "browser" | "dns" | "registration" | "email" | "payments" | |
| components.name (required) | string | |
| components.state (required) | "operational" | "degraded" | "outage" | "maintenance" | "unknown" | |
| components.since | string or null | |
| 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 | |
| components.uptime_90d | number or null | Percent of sampled minutes without an outage, last 90 days |
| components.days | array of object | |
| registration (required) | object | |
| registration.checked_at | string or null | |
| registration.tlds_total | integer | |
| registration.tlds_ok | integer | |
| registration.failing_tlds | array of string | |
| incidents (required) | object | |
| incidents.open | array of object | |
| incidents.recent | array of object | 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
curl "https://api.dnssuper.com/v1/status" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"