DNS Toolbox

API reference

The same REST API the app uses, opened to your scripts with an API key. Read your domains, scans, uptime monitors, expiry facts and alerts; add domains; run scans and checks.

Authentication

Create a key under Settings → API keys in the app (owner or admin; available on plans with API access). A key looks like dnt_ followed by 40 hex characters and is shown once — only its hash is stored. Choose a scope: read (every GET) or read + write (also POST, PATCH, DELETE on resources). Keys can carry an expiry, and revocation is immediate.

Send it as a bearer token:

curl \
  -H "Authorization: Bearer dnt_0123456789abcdef0123456789abcdef01234567" \
  https://dnstoolbox.app/wp-json/dnt/v1/domains

A key acts as the account owner, in the owner's account. Team-switching headers are ignored.

Requests & responses

Base URL
https://dnstoolbox.app/wp-json/dnt/v1

JSON in, JSON out. Send request bodies as application/json. Dates and times are UTC in YYYY-MM-DD HH:MM:SS form. Booleans are real booleans. Ids are integers.

Every response to a keyed request carries X-DNT-Key (the key's prefix), X-RateLimit-Limit and X-RateLimit-Remaining.

Limits

Domains & scans

MethodPathWhat it does
GET/domainsYour portfolio: domains[] with id (portfolio id), domain_id, name, health_score, module_scores, last_scan_at, modules (what is attached), expiry (registration and certificate facts).
POST/domainsAdd a domain: {"domain": "example.com"}. Runs the first scan. Returns {domain, scan}.
GET/domains/{id}One portfolio entry.
POST/domains/{id}/scanStart a full scan; returns the scan id. Poll /scans/{scan_id} until status is completed.
GET/domains/{id}/reportThe latest report: scores, findings, module data (?scan_id= for an older one).
GET/domains/{id}/scansScan history.
GET/domains/{id}/timelineChanges detected over time (DNS, certificate, headers…).
GET/domains/{id}/compare?a=&b=Diff two scans.
GET/domains/{id}/modulesEverything configured for the domain across modules (uptime, WordPress, DMARC, SPF…).
GET/domains/{id}/exportThe latest report as CSV.
PATCH / DEL/domains/{id}Edit label/tags, or remove from the portfolio.
GET / POST/scans/{scan_id}Scan status and result; scans are advanced by the poll, so keep polling every few seconds.

Example: add a domain and wait for its scan

curl -X POST \
  -H "Authorization: Bearer dnt_0123456789abcdef0123456789abcdef01234567" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}' \
  https://dnstoolbox.app/wp-json/dnt/v1/domains
# → { "domain": { "id": 42, "name": "example.com", … }, "scan": { "scan_id": 918, "status": "queued" } }

curl \
  -H "Authorization: Bearer dnt_0123456789abcdef0123456789abcdef01234567" \
  https://dnstoolbox.app/wp-json/dnt/v1/scans/918
# → { "status": "completed", "health_score": 91, "modules": { "dns": 93, "website": 95, … } }

Uptime

MethodPathWhat it does
GET/uptimechecks[] with status (up, down, blocked, unknown), uptime_24h, last_ms, last_checked_at, blocked_by, last_confirmation.
POST/uptimeCreate a monitor: {"type":"http","url":"https://example.com/","label":"Site","interval_minutes":5}. Types: http, api, ping, port, dns, heartbeat. Keyword checks add keyword and keyword_mode.
GET/uptime/{id}?hours=24Detail: 24 h / 7 d / 30 d uptime, response history, incidents with confirmed_by.
POST/uptime/{id}/checkProbe now, inline (1–20 s), confirmation from other locations included. Returns {outcome: {up, blocked, code, ms, error}, check}.
PATCH / DEL/uptime/{id}Edit (enabled, label, interval_minutes, notify…) or delete.

About blocked. A monitor is blocked when the site drops our monitoring address while other locations reach it. That is not an outage: no incident is opened and history counts it as up. Allow the addresses listed at /bot in the site's firewall to get direct checks again.

Everything else

AreaPathsNotes
AlertsGET /notificationsWhat your monitors reported, with category, severity, status (sent, held…), items.
DashboardGET /dashboardPortfolio summary, average health, top issues, recent scans and changes, expiring (registrations and certificates within 60 days).
WordPress healthGET /wordpress, GET /wordpress/{id}, POST /wordpress/{id}/checkConnected sites, their health score and findings; check now.
PerformanceGET /performance, GET /performance/{id}?days=30, POST /performance/{id}/runPageSpeed history (mobile and desktop scores, Core Web Vitals); queue a run.
PropagationGET /propagation, POST /propagationWatches for a DNS change across public resolvers.
Hosted SPFGET /spf, GET /spf/{id}, POST /spf/{id}/refresh, POST /spf/{id}/verifyFlattened SPF zones, versions, verification.
Status pagesGET /status-pages; public: GET /public/status/{slug}The public JSON needs no key at all.
Scheduled reportsGET /scheduled-reports, POST /scheduled-reports/{id}/runSchedules and generated files (download links work without a key for 90 days).

Write scope is required for every POST, PATCH and DELETE above.

Errors

Errors are {"code": "…", "message": "…", "data": {"status": 4xx}}.

StatusCodeMeaning
401dnt_api_key_invalidUnknown, revoked or expired key.
403dnt_api_scopeA read key on a write route, or something only a person may do.
403dnt_api_routeThe endpoint is outside what keys may reach (see below).
403dnt_planYour plan's limit for that resource is reached, or the feature is not included.
404dnt_not_foundNot yours, or gone.
400dnt_invalid, dnt_invalid_domainValidation; the message says which field.
409dnt_duplicateAlready exists in this account.
429dnt_rate_limitedToo many requests; data.retry_after seconds.

What keys cannot do

Revoke a key from Settings → API keys the moment you no longer need it. Keys record their last use and address so you can tell which script is which.