Docs menu

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)

NameTypeDescription
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 objectLast 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
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
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

NameTypeDescription
cursorstring or null`next_cursor` from the previous page
limitintegerJobs per page
status"unfinished" | "finished" | "all"Which jobs to list
kind"tool" | "bulk" | "all"Tool jobs, bulk checks or both

Response (200)

NameTypeDescription
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)integerRows in the job
items.done (required)integerRows with a result (charged)
items.failed (required)integerRows whose sources didn't answer (not charged)
items.credits_reserved (required)integerCredits held when the job was submitted
items.credits_used (required)integerCredits 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.progressobject or nullThe running row's own progress, such as pages crawled; null when none
items.labelstring or nullThe label given when it was submitted
items.bulkbooleanTrue for a bulk check
items.estimated_remaining_sinteger or nullSeconds 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 nullPass 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
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

NameTypeDescription
job_id (required)stringThe job's ID

Response (200)

NameTypeDescription
id (required)string
tool (required)string
status (required)"queued" | "running" | "cancelling" | "done" | "cancelled" | "failed"
total (required)integerRows in the job
done (required)integerRows with a result (charged)
failed (required)integerRows whose sources didn't answer (not charged)
credits_reserved (required)integerCredits held when the job was submitted
credits_used (required)integerCredits 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
progressobject or nullThe running row's own progress, such as pages crawled; null when none
labelstring or nullThe label given when it was submitted
bulkbooleanTrue for a bulk check
estimated_remaining_sinteger or nullSeconds 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
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

NameTypeDescription
job_id (required)stringThe job's ID

Query parameters

NameTypeDescription
afterintegerReturn rows after this row number
limitintegerRows per page

Response (200)

NameTypeDescription
items (required)array of object
items.row (required)integerRow 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 nullThe row's result envelope; null until it is done, and after 7 days
next_after (required)integer or nullPass 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
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

NameTypeDescription
job_id (required)stringThe job's ID

Response (200)

NameTypeDescription
id (required)string
tool (required)string
status (required)"queued" | "running" | "cancelling" | "done" | "cancelled" | "failed"
total (required)integerRows in the job
done (required)integerRows with a result (charged)
failed (required)integerRows whose sources didn't answer (not charged)
credits_reserved (required)integerCredits held when the job was submitted
credits_used (required)integerCredits 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
progressobject or nullThe running row's own progress, such as pages crawled; null when none
labelstring or nullThe label given when it was submitted
bulkbooleanTrue for a bulk check
estimated_remaining_sinteger or nullSeconds 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
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

NameTypeDescription
job_id (required)stringThe 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
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

NameTypeDescription
tool (required)stringRegistry id of the tool

Query parameters

NameTypeDescription
dry_runbooleanShow the rows, errors, credits and time without starting the job
skip_invalidbooleanRun only the valid rows instead of refusing the job

Request body

NameTypeDescription
targetsarray of any or nullNames to check, one per row
rowsarray of object or nullRows of the tool's own input properties
csvstring or nullThe text of a CSV file: a header naming the tool's inputs, one row per check
optionsobjectJob-wide parameters for every row: `fresh`, variant and per-unit options, and any shared tool parameter
labelstring or nullYour name for the job
notifyobject or nullSend a notice to this alert channel when the job finishes
check_ownershipbooleanDry runs only: also check the TXT ownership records (subdomain takeover)

Response (200)

NameTypeDescription
tool (required)string
rows (required)integerRows sent
unique (required)integerValid rows that would run after removing duplicates
duplicates_removed (required)integer
invalid (required)integerRows with an error
errors (required)array of objectThe first 100 row errors
errors.row (required)integerCSV line (1-based) or position in the list
errors.column (required)string or null
errors.message (required)string
columns (required)array of stringThe input each column was read as
preview (required)array of objectThe first 5 valid rows
preview.row (required)integer
preview.target (required)string
preview.options (required)object
limit (required)integerThe most rows one bulk check with this tool may have
credits (required)integerCredits the job would hold when it starts
balance (required)integerYour balance now
estimated_max_s (required)integerThe longest the job could take, if every row is as slow as it can be
unverified (required)array of stringDomains still needing their TXT ownership record (at most 20)
recordsarray of objectThe 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)booleanTrue 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
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

NameTypeDescription
domain (required)string

Response (200)

NameTypeDescription
domain (required)stringThe registrable domain the record proves
record_name (required)stringWhere to publish the TXT record
record_value (required)stringThe 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
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

NameTypeDescription
domain (required)string

Response (200)

NameTypeDescription
domain (required)string
verified (required)booleanTrue 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
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

NameTypeDescription
tool (required)stringRegistry id of the tool
inputobjectThe tool's parameters, as for its own endpoint
freshbooleanSkip the cache and ask the sources again

Response (202)

NameTypeDescription
stream_id (required)stringOpaque id of the run's event stream
stream_url (required)stringOpen this for the events (GET, text/event-stream)
request_id (required)stringThis call's request id, the ledger reference
free_checks_remaininginteger or nullWebsite 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
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

NameTypeDescription
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
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

NameTypeDescription
stream_id (required)string`stream_id` from POST /v1/streams

Query parameters

NameTypeDescription
waitintegerSeconds to wait for the last event

Response (200)

NameTypeDescription
done (required)booleanTrue when the last event is included
events (required)array of object
events.id (required)stringThe 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
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

NameTypeDescription
cursorstring or null
limitinteger
state"active" | "all"

Response (200)

NameTypeDescription
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 nullPass 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
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

NameTypeDescription
source (required)objectWhere the result comes from: a call's request id, or a job row.
expires_in_daysintegerDays until the link stops working (1 to 90)
passwordstring or nullOptional: visitors must enter it to open the link. Never stored in plain text

Response (201)

NameTypeDescription
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
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

NameTypeDescription
share_id (required)stringThe shared report's ID

Response (200)

NameTypeDescription
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
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

NameTypeDescription
share_id (required)stringThe 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
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

NameTypeDescription
cursorstring or null
kindstring or null
health"ok" | "warn" | "fail" | "unknown" or null
status"active" | "paused" | "limited" or null
limitinteger

Response (200)

NameTypeDescription
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 nullplan_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
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

NameTypeDescription
kind (required)"domain-expiry" | "ssl" | "dns" | "uptime" | "page-change" | "score-drop" | "lookalikes"What to watch
target (required)stringA domain (domain-expiry, ssl, dns, lookalikes) or a URL (uptime, page-change, score-drop)
intervalinteger or nullSeconds between checks; default: the kind's longest interval your plan allows
optionsobjectOptions for this kind (see the docs)
rulesobject
channel_idsarray of string or nullAlert channels; null: the account's default email channel
labelstring or null

Response (201)

NameTypeDescription
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 nullplan_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
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

NameTypeDescription
monitor_id (required)stringThe monitor's ID

Response (200)

NameTypeDescription
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 nullplan_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
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

NameTypeDescription
monitor_id (required)stringThe monitor's ID

Request body

NameTypeDescription
labelstring or null
intervalinteger or null
optionsobject or null
rulesobject or null
channel_idsarray of string or null
pausedboolean or null

Response (200)

NameTypeDescription
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 nullplan_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
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

NameTypeDescription
monitor_id (required)stringThe 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
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

NameTypeDescription
monitor_id (required)stringThe monitor's ID

Response (202)

NameTypeDescription
acceptedboolean
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
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

NameTypeDescription
monitor_id (required)stringThe monitor's ID

Query parameters

NameTypeDescription
cursorstring or null
limitinteger

Response (200)

NameTypeDescription
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
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

NameTypeDescription
monitor_id (required)stringThe monitor's ID

Query parameters

NameTypeDescription
daysinteger7, 30 or 90

Response (200)

NameTypeDescription
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
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)

NameTypeDescription
channels (required)array of object
channels.id (required)string
channels.type (required)string
channels.name (required)string
channels.hint (required)string or nullA 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)booleanFalse while alert delivery is off on this server
bulk_unlockedbooleanTrue 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
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

NameTypeDescription
type (required)"email" | "webhook" | "slack"
name (required)string
urlstring or null
recipientsarray of string or null
digestboolean
digest_hourinteger
jobs_onlyboolean

Response (201)

NameTypeDescription
id (required)string
type (required)string
name (required)string
hint (required)string or nullA shortened form of the URL; never the full URL
recipients (required)array of object
recipients.user_id (required)string
recipients.email (required)string or nullnull 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_secretstring or nullWebhooks 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
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

NameTypeDescription
channel_id (required)stringThe alert channel's ID

Request body

NameTypeDescription
namestring or null
urlstring or null
recipientsarray of string or null
digestboolean or null
digest_hourinteger or null
pausedboolean or null

Response (200)

NameTypeDescription
id (required)string
type (required)string
name (required)string
hint (required)string or nullA shortened form of the URL; never the full URL
recipients (required)array of object
recipients.user_id (required)string
recipients.email (required)string or nullnull 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
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

NameTypeDescription
channel_id (required)stringThe 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
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

NameTypeDescription
channel_id (required)stringThe alert channel's ID

Response (200)

NameTypeDescription
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
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

NameTypeDescription
channel_id (required)stringThe alert channel's ID

Response (202)

NameTypeDescription
id (required)string
kind (required)string
status (required)string
attempts (required)integer
status_class (required)string or null2xx, 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
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

NameTypeDescription
channel_id (required)stringThe alert channel's ID

Response (200)

NameTypeDescription
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
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

NameTypeDescription
channel_id (required)stringThe alert channel's ID

Query parameters

NameTypeDescription
cursorstring or null
limitinteger

Response (200)

NameTypeDescription
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 null2xx, 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
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)

NameTypeDescription
active (required)booleanWhether the account has a feed URL that works
created_at (required)string or nullWhen the current URL was made
last_fetched_at (required)string or nullWhen a calendar app last fetched it (updated at most hourly)
domains (required)integerDomain-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
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)

NameTypeDescription
url (required)stringThe 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
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
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
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

NameTypeDescription
cursorstring or null
limitinteger

Response (200)

NameTypeDescription
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_urlstring or nullWhere 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
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

NameTypeDescription
source (required)anyWhat 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
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

NameTypeDescription
export_id (required)stringThe export's ID

Response (200)

NameTypeDescription
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_urlstring or nullWhere 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
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

NameTypeDescription
export_id (required)stringThe 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
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

NameTypeDescription
export_id (required)stringThe 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
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)

NameTypeDescription
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.sincestring 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_90dnumber or nullPercent of sampled minutes without an outage, last 90 days
components.daysarray of object
registration (required)object
registration.checked_atstring or null
registration.tlds_totalinteger
registration.tlds_okinteger
registration.failing_tldsarray of string
incidents (required)object
incidents.openarray of object
incidents.recentarray of objectResolved 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
curl "https://api.dnssuper.com/v1/status" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"