Authentication
Admins and owners create API tokens in the dashboard under Settings → API. The token is shown in plain text exactly once; afterwards only name, scope, last use and expiry remain visible. Every call sends the token as a bearer token and requests JSON:
- A token is valid for exactly one organization. Calls for another organization respond with 404, as if it did not exist.
- Optional expiry of 1 to 730 days; 90 days with regular rotation is recommended. Expired and revoked tokens respond with 401.
- If the creator leaves the organization or the organization is deleted, their tokens become invalid immediately.
- At most 20 tokens per organization. Every creation and revocation is recorded in the audit log.
Authorization: Bearer <token>
Accept: application/jsonScopes: read and write
When creating a token you choose between two scopes. A token never has more rights than a member, even if an owner created it.
- read: like the viewer role. All GET endpoints; every writing method responds with 403.
- write: like the member role. Additionally create, update and delete domains and customers, manage monitors, trigger checks and acknowledge incidents.
- Never via token, not even with write: account, password, two-factor, passkeys, members, invitations, billing, notification channels, audit log, data export and token management itself. These routes respond with 403.
Base URL and language
All endpoints live under https://api.domainwarn.com/api/v1; the data of an organization under /orgs/{organization}. You find the slug in the dashboard URL, under Settings → API, or via GET /organizations, which with a token returns exactly that one organization.
Findings (findings) are translated: the header Accept-Language: de or en selects the language, without it English is used. All timestamps are ISO 8601 in UTC (suffix Z), IDs are UUIDs.
Limits
- 300 requests per minute and token, independent of the creator's dashboard session. The headers
X-RateLimit-LimitandX-RateLimit-Remainingshow the state; when exceeded the server responds with 429 andRetry-Afterin seconds. - Check now: 5 calls per domain and hour, 60 per organization and hour.
- Bulk import: 200 domains per call, 3 calls per hour and organization.
- The domain limit of the plan also applies to the API. Domains created beyond it respond with 422; domains above the limit of a smaller plan are
plan_paused.
Responses and errors
Successful responses carry the payload under data; lists additionally links and meta. Creating responds with 201, deleting with 204 without content, triggering checks with 202. Every error comes as application/problem+json (RFC 9457) with type, title, status and usually detail:
- 401: token missing, expired or revoked.
- 402: the organization is suspended or has no active plan;
planandsuspendedsay why. - 403: the token is not allowed to do this (read token on a writing method, blocked area).
- 404: organization or object not found, also for a foreign organization.
- 422: invalid input;
errorscontains the messages per field. - 429: limit exceeded, see
Retry-After.
{
"type": "https://domainwarn.com/errors/validation",
"title": "The input is invalid.",
"status": 422,
"detail": "The name field is required.",
"errors": { "name": ["The name field is required."] }
}Pagination
Domains and customers are paginated by page: page and per_page as parameters, meta.current_page, meta.last_page and meta.total in the response. Incidents, events and check results are sorted by time and cursor-paginated: the response names the cursor of the next page in meta.next_cursor (links.next for check results), which you pass as the cursor parameter; null means the end.
GET /orgs/my-agency/incidents?status=open&per_page=100
GET /orgs/my-agency/incidents?status=open&per_page=100&cursor=eyJzdGFydGVkX2F0Ijoi…Example: query critical domains
All domains in a critical state, sorted by health, as input for a ticket system or a Slack bot:
curl -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
"https://api.domainwarn.com/api/v1/orgs/my-agency/domains?status=critical,warning&sort=health_status"Example: create and check a domain from CI
After a client site goes live, the pipeline creates the domain and triggers the first check right away. The create response contains the id for all further calls:
curl -X POST -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
-H "Content-Type: application/json" -d '{"name":"client.com","customer_id":"3f9c1a52-6a2e-4c0e-9d4b-1c9a1a0e5b77"}' \
"https://api.domainwarn.com/api/v1/orgs/my-agency/domains"
curl -X POST -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
"https://api.domainwarn.com/api/v1/orgs/my-agency/domains/<domain-id>/check-now"Code examples for curl, PHP, Python, JavaScript, Go and PowerShell
Pick a language or tool and a use case; replace <TOKEN> with your token. Use cases with write access are marked and need a token with write scope.
GET /domainsA read token is enoughcurl "https://api.domainwarn.com/api/v1/orgs/my-agency/domains?status=critical,warning&sort=health_status" \
-H "Authorization: Bearer <TOKEN>" \
-H "Accept: application/json"“my-agency” stands for the slug of your organization; under Settings → API in the dashboard the examples show your own address.
Asking in your editor (MCP)
DomainWarn is an MCP server itself: POST /mcp speaks the Model Context Protocol, and editors and assistants connect with one address plus the token – nothing to install. The assistant then answers questions like “Which client domains are critical right now?” or “Check example.com” with your real data.
Nine tools in three tiers: without a token the free checks run (check_domain, run_check), with a token list_domains, get_domain, list_incidents and get_dns_history come along, and a token with write scope unlocks add_domain, check_now and acknowledge_incident. With a read token the writing tools never even appear.
Run in the terminal; with --scope user DomainWarn is available in every project.
claude mcp add --transport http domainwarn https://api.domainwarn.com/api/v1/mcp \
--header "Authorization: Bearer <TOKEN>"Connecting monitoring systems
Prometheus, Grafana Alloy, VictoriaMetrics, Telegraf and Datadog read the metrics of all domains in Prometheus format at /orgs/{organization}/metrics; Checkmk, Nagios/Icinga, Uptime Kuma and PRTG query the JSON overview /orgs/{organization}/dashboard and alert as soon as a domain is critical. Pick your system and copy the ready-made configuration:
Scrape job for prometheus.yml; afterwards all metrics are available to Grafana and Alertmanager. (Uses the Prometheus metrics)
scrape_configs:
- job_name: domainwarn
scheme: https
metrics_path: /api/v1/orgs/my-agency/metrics
scrape_interval: 60s
static_configs: [{ targets: ['api.domainwarn.com'] }]
authorization: { credentials: '<TOKEN>' }“my-agency” stands for the slug of your organization; under Settings → API in the dashboard the examples show your own address.
OpenAPI specification
The complete description of all endpoints, parameters, schemas and errors is available as OpenAPI 3.1 at /openapi.json in the language of this page. Use it to generate clients (openapi-generator, orval, Kiota), import the API into Postman, Insomnia or Bruno, or open it in the Swagger Editor. The specification is built from the same source as this page and changes with every release of the API.