API

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.

DNS Records API

Add, change, delete, and check DNS records, and each record type's value format.

Zone Files API

Import and export many DNS records at once.

Events API

Poll for status changes, or use webhooks to get notified the moment one happens.

Conventions

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:


DNS monitoring illustration

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