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
- 1000 requests per key per clock hour. Over that,
429withretry_afterseconds in the body. - Up to 10 live keys per account.
- Plan limits apply exactly as in the app: adding a domain beyond your plan returns
403 dnt_plan. - Some actions have their own throttle (for example "check now" on a monitor: 10 per hour per monitor); the error names it.
Domains & scans
| Method | Path | What it does |
|---|---|---|
| GET | /domains | Your 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 | /domains | Add a domain: {"domain": "example.com"}. Runs the first scan. Returns {domain, scan}. |
| GET | /domains/{id} | One portfolio entry. |
| POST | /domains/{id}/scan | Start a full scan; returns the scan id. Poll /scans/{scan_id} until status is completed. |
| GET | /domains/{id}/report | The latest report: scores, findings, module data (?scan_id= for an older one). |
| GET | /domains/{id}/scans | Scan history. |
| GET | /domains/{id}/timeline | Changes detected over time (DNS, certificate, headers…). |
| GET | /domains/{id}/compare?a=&b= | Diff two scans. |
| GET | /domains/{id}/modules | Everything configured for the domain across modules (uptime, WordPress, DMARC, SPF…). |
| GET | /domains/{id}/export | The 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
| Method | Path | What it does |
|---|---|---|
| GET | /uptime | checks[] with status (up, down, blocked, unknown), uptime_24h, last_ms, last_checked_at, blocked_by, last_confirmation. |
| POST | /uptime | Create 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=24 | Detail: 24 h / 7 d / 30 d uptime, response history, incidents with confirmed_by. |
| POST | /uptime/{id}/check | Probe 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
| Area | Paths | Notes |
|---|---|---|
| Alerts | GET /notifications | What your monitors reported, with category, severity, status (sent, held…), items. |
| Dashboard | GET /dashboard | Portfolio summary, average health, top issues, recent scans and changes, expiring (registrations and certificates within 60 days). |
| WordPress health | GET /wordpress, GET /wordpress/{id}, POST /wordpress/{id}/check | Connected sites, their health score and findings; check now. |
| Performance | GET /performance, GET /performance/{id}?days=30, POST /performance/{id}/run | PageSpeed history (mobile and desktop scores, Core Web Vitals); queue a run. |
| Propagation | GET /propagation, POST /propagation | Watches for a DNS change across public resolvers. |
| Hosted SPF | GET /spf, GET /spf/{id}, POST /spf/{id}/refresh, POST /spf/{id}/verify | Flattened SPF zones, versions, verification. |
| Status pages | GET /status-pages; public: GET /public/status/{slug} | The public JSON needs no key at all. |
| Scheduled reports | GET /scheduled-reports, POST /scheduled-reports/{id}/run | Schedules 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}}.
| Status | Code | Meaning |
|---|---|---|
| 401 | dnt_api_key_invalid | Unknown, revoked or expired key. |
| 403 | dnt_api_scope | A read key on a write route, or something only a person may do. |
| 403 | dnt_api_route | The endpoint is outside what keys may reach (see below). |
| 403 | dnt_plan | Your plan's limit for that resource is reached, or the feature is not included. |
| 404 | dnt_not_found | Not yours, or gone. |
| 400 | dnt_invalid, dnt_invalid_domain | Validation; the message says which field. |
| 409 | dnt_duplicate | Already exists in this account. |
| 429 | dnt_rate_limited | Too many requests; data.retry_after seconds. |
What keys cannot do
- Manage people or secrets: team members and invitations, alert channels, other API keys, notification preferences. Those need someone signed in to the app.
- Sign in or register (
/auth/*). - Touch anything outside
/dnt/v1. A key is not a WordPress login; core routes reject it.
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.