With the DNS Check API, you can create and organize DNS record groups, add the DNS records to monitor, check them on demand, and read their status and history. It covers all 14 DNS record types that DNS Check monitors.
The current version is API v2, at https://www.dnscheck.co/api/v2. It's a JSON API over HTTPS that every DNS Check account can use. API v1 is also supported for existing integrations.
Requests need an API key, sent as Authorization: Bearer dnscheck_.... Add one on the API Keys page.
You can try the API before creating an account: the example record group and its DNS records and events can be read without an API key.
curl https://www.dnscheck.co/api/v2/record-groups/ea883d67-d9f6-45e3-b3a1-844dd1857824
Endpoints
Each endpoint is covered on its resource page. API Errors lists every error code the endpoints return.
Record Groups API
List, create, change, and delete record groups.
-
List the account's record groups
GET /api/v2 /record-groups -
Create a record group
POST /api/v2 /record-groups -
Get a record group
GET /api/v2 /record-groups /{id} -
Update a record group
PATCH /api/v2 /record-groups /{id} -
Delete a record group
DELETE /api/v2 /record-groups /{id}
DNS Records API
Add, change, delete, and check DNS records, and each record type's value format.
-
List the DNS records in a record group
GET /api/v2 /record-groups /{id} /dns-records -
Add a DNS record to a record group
POST /api/v2 /record-groups /{id} /dns-records -
List all the account's DNS records
GET /api/v2 /dns-records -
Get a DNS record
GET /api/v2 /dns-records /{id} -
Update a DNS record
PATCH /api/v2 /dns-records /{id} -
Delete a DNS record
DELETE /api/v2 /dns-records /{id} -
Check a DNS record on demand
POST /api/v2 /dns-records /{id} /check
Zone Files API
Import and export many DNS records at once.
-
Export a record group as a zone file
GET /api/v2 /record-groups /{id} /zone-file -
Import a zone file
POST /api/v2 /record-groups /{id} /zone-file /import
Events API
Poll for status changes, or use webhooks to get notified the moment one happens.
-
List a DNS record's events
GET /api/v2 /dns-records /{id} /events -
Read the account's event feed
GET /api/v2 /events
Conventions
- Authentication: send an API key as
Authorization: Bearer dnscheck_.... A Read-only key can make only GET requests. The API Keys documentation covers adding keys and configuring their access level. - Call the API from a server, not a browser: it doesn't send CORS headers, which keeps API keys out of web pages.
- Requests and responses are JSON. A single resource is returned as the object itself, with an
objectfield naming its type. Most objects also have anid. Field names aresnake_case, and timestamps are RFC 3339 in UTC. - IDs are opaque strings. A record group's ID is in its web page's URL.
- Lists look like
{"data": [...], "next_cursor": "...", "has_more": true}. Whilehas_moreistrue, passnext_cursorback as thecursorquery parameter for the next page. Thelimitquery parameter sets the page size, from 1 to 200 (default 50). The event feed'snext_cursoris nevernull, even whenhas_moreisfalse, so you can keep it to read new events later. - Filters are query parameters too, such as
?status=failing, and can be combined, listing only what matches all of them. A query parameter the endpoint doesn't take, such as a misspelled filter, gets a400with the codeinvalid_parameterrather than being ignored. - Updates use
PATCHwith only the fields you're changing (JSON merge patch), sent asapplication/jsonorapplication/merge-patch+json. Endpoints refuse unrecognized fields, so a typo can't go unnoticed. - Compatibility: new endpoints, fields, optional parameters, and values can be added to v2 at any time, so ignore unrecognized fields, and handle new values in fields such as
type,status,check_frequency, or errorcode. Anything that would break an existing client waits for a new version, except rate limits and similar abuse protections, which can be added or changed at any time. The API Changelog lists each change with its date.
Status Codes
| Status | When |
|---|---|
200 |
A read, an update, a POST that runs an action rather than creating something (a zone file import) |
201 |
A create, with a Location header naming the new resource's URL |
202 |
An on-demand check, queued to run within a few seconds |
204 |
A delete, with no body |
304 |
A GET whose If-None-Match names the current ETag |
4xx, 5xx |
An error, as RFC 9457 Problem Details with a stable code, except an error page from Cloudflare, which sits in front of DNS Check, such as a 5xx when DNS Check can't be reached (see API Errors) |
API Errors lists each code with its status and how to resolve it, which errors are worth retrying, and what to do with a 5xx that has no Problem Details.
Rate Limits
Limits are per account, shared by all of its keys:
| Limit | Basic | Professional | Enterprise |
|---|---|---|---|
| Requests per minute | 11 | 110 | 1,100 |
| Writes per minute | 10 | 100 | 1,000 |
| Writes per day | 100 | 1,000 | 10,000 |
| On-demand checks per minute | 1 | 10 | 100 |
Each plan's limits follow its DNS record limit, so plans with more DNS records get proportionally higher ones. Writes per minute equal the DNS record limit. Requests per minute are 10% more, so you can read each DNS record once a minute and still have room for other requests. On-demand checks per minute are 10% of the DNS record limit.
To hear about a status change as soon as possible, use webhooks instead of polling. A webhook is usually sent within 5 seconds of the check that changes a DNS record's status.
Every limited response carries RateLimit-Policy and RateLimit headers (from draft-ietf-httpapi-ratelimit-headers-11) listing each budget the request drew on. A write's RateLimit looks like this:
RateLimit: "requests";r=994;t=49, "writes";r=998;t=49, "writes-daily";r=9989;t=85429
r is how much is left, and t is the seconds until it resets. requests counts every request, including writes, and a check draws on a checks budget.
Over a limit, you get a 429 with a Retry-After header giving the seconds to wait.
What Counts as a Write
Each request counts as one write, except a zone file import, which counts the DNS records it changes:
| Request | Writes |
|---|---|
| Add, change, or delete a DNS record | 1 |
| Create, change, or delete a record group, including every DNS record in it | 1 |
| Zone file import | The larger of the number of DNS records it adds and the number it deletes, plus the number it updates. DNS records it leaves unchanged are free. |
A request that needs more writes than are left is refused whole, so nothing in it is saved. Wait and retry, or, if it needs more than the plan allows in a minute (too_many_writes), split it into smaller requests. The daily quota resets at midnight UTC.
Idempotency and ETags
Idempotency Keys
Send an Idempotency-Key header, such as a random UUID, with any POST. It can be up to 255 characters long. If the connection drops and you retry with the same key within 24 hours, you get the first request's response, marked Idempotent-Replayed: true, instead of a second record group or DNS record.
IDEMPOTENCY_KEY=$(openssl rand -hex 16)
curl https://www.dnscheck.co/api/v2/record-groups \
-H "Authorization: Bearer $DNSCHECK_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{"name": "Mail", "public": false}'
To retry a request safely, run the curl command again with the same key. Generate a new key for each new request.
Validation and plan limit errors are replayed too. A 429, a 5xx, or a request refused due to an invalid API key or a malformed body isn't stored, so retrying it runs it again.
Idempotency keys are kept per API key. Reusing one for a request with a different method, path, or body gets idempotency_key_reused, and retrying while the first request is still running gets idempotency_key_in_use.
ETags
Every GET response comes with an ETag header. Send it back as If-None-Match to get an empty 304 while the response is unchanged, such as when polling the event feed with no new events. A 304 still counts as a request.
A single record group's or DNS record's ETag also works as If-Match on a PATCH or DELETE: the write is refused with 412 if someone edited the resource since you read it. Checks don't count as edits. The examples for updating a record group or a DNS record show how to read an ETag and send it.
OpenAPI Document
The OpenAPI document describes API v2 in OpenAPI 3.1, including each endpoint, field, and error code, and the version 2 webhook envelopes. You can use it to:
- Try requests: import its URL into an API client such as Postman or Insomnia to get every request with its parameters, grouped by resource, then set your API key once as the Bearer token.
- Generate a client library: generators such as OpenAPI Generator build typed clients from it, and types for your webhook endpoint. Most generated clients won't wait out a
429or fill in anIdempotency-Keyfor you, so handle those in your own code. - Give an AI agent the API as tools: agent frameworks and MCP servers that load OpenAPI documents turn each endpoint into a tool, named by its
operationId, such ascreateDnsRecord.
Protect your DNS infrastructure with automated monitoring
Get notified immediately when DNS records change. Start monitoring your critical DNS infrastructure for free in under 5 minutes.
No credit card required • Cancel anytime