Skip to Content
Uptimeify Docs
MonitorsDns monitors

Create DNS Monitor

Creates a new DNS monitor for a customer.

POST /api/dns-monitors

Request Body

{
  "customerId": "6bfec6f6-245a-47ce-843b-157d97d56f88",
  "name": "Example DNS",
  "hostname": "deinkunde.com",
  "status": "active",
  "checkInterval": 30,
  "timeoutSeconds": 30,
  "allowedCheckCountryCodes": ["DE", "FR"],
  "dnsConfig": {
    "rrtypes": ["A", "AAAA"],
    "matchMode": "exact",
    "expectedValues": {
      "A": ["93.184.216.34"],
      "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"]
    },
    "triggerOn": {
      "resolveError": true,
      "mismatch": true
    }
  }
}

Notes:

  • customerId, name, hostname, dnsConfig.rrtypes, dnsConfig.matchMode, and dnsConfig.expectedValues are required.
  • customerId accepts either the internal numeric ID or the customer publicId UUID.
  • Global supporters cannot create DNS monitors. A readonly or customer-scoped login may create one inside its own customer scope; the monitor is then forced to self_service and refused with selfServiceNotAllowed or selfServiceQuotaReached when the package does not allow it or the quota is used up.
  • hostname must be a hostname (no protocol, no path).
  • dnsConfig.expectedValues must contain at least one expected value for every RR type listed in dnsConfig.rrtypes.
  • allowedCheckCountryCodes (string[], optional)
    • Restricts checks to these ISO-3166-1 alpha-2 country codes.
    • Each entry must be exactly two letters; entries are trimmed, upper-cased and deduplicated before they are stored.
    • Omit the key, send null or send an empty array to drop the restriction on the monitor; a restriction set on the customer itself still applies.
    • The two-letter rule checks the form only: a country code without an active check location is accepted, and the monitor then never runs a check.

Duplicates

If this customer already has a monitor with the same hostname (case and a trailing dot do not count) and the same set of record types in dnsConfig.rrtypes, the request is refused with 409 and data.code monitorAlreadyExists. data.existingId and data.existingPublicId name the existing monitor. Send "allowDuplicate": true to create the second monitor anyway (for example with a different interval or other alert channels).

  • allowDuplicate (boolean, optional, default false): create the monitor even if it is a duplicate. Not stored.
{
  "statusCode": 409,
  "statusMessage": "A monitor for this target already exists for this customer. Send allowDuplicate: true to create it anyway.",
  "data": { "code": "monitorAlreadyExists", "existingId": 300, "existingPublicId": "44444444-4444-4444-8444-444444444444" }
}

Limit per target host

An organization can have at most 100 monitors for the same target host, counted across all monitor types together (websites with HTTP, keyword, DNS website and Playwright with a real URL, plus TCP, ICMP, DNS, SSH, SMTP, FTP and IMAP/POP). The limit protects against the check fleet being misused as a load generator against third-party hosts. The exact hostname is compared: case, port, path and a trailing dot do not count, but www.example.com and example.com are different hosts. Once the limit is reached, the request is refused with 403 and data.code targetHostMonitorLimitReached. data.host names the normalized host, data.limit the limit. "allowDuplicate": true does not lift the limit. The same check runs when a PATCH changes the hostname. A PATCH that keeps the host always succeeds, and existing monitors above the limit stay in place. If you need a higher limit, contact support. Independently of your organization, at most 300 monitors across all Uptimeify customers may target the same host. Beyond that, the request is refused with 403 and data.code targetHostPlatformLimitReached; data.host and data.limit are set as above, and the message does not reveal how many monitors other organizations have.

{
  "statusCode": 403,
  "statusMessage": "Target host monitor limit reached: your organization already has 100 monitors for example.com (maximum 100 per host). Remove monitors for this host or contact support to raise the limit.",
  "data": { "code": "targetHostMonitorLimitReached", "host": "example.com", "limit": 100 }
}

Example (cURL)

BASE_URL="https://uptimeify.io"
TOKEN="<your-api-token>"

curl -X POST \
  "$BASE_URL/api/dns-monitors" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"6bfec6f6-245a-47ce-843b-157d97d56f88","name":"Example DNS","hostname":"deinkunde.com","allowedCheckCountryCodes":["DE","FR"],"dnsConfig":{"rrtypes":["A"],"matchMode":"exact","expectedValues":{"A":["93.184.216.34"]},"triggerOn":{"resolveError":true,"mismatch":true}}}'

Common errors

  • 400 Invalid Customer identifier
  • 400 hostname must be a valid hostname (no protocol, no path)
  • 400 Expected values are required for RR type <TYPE>
  • 400 Bad Request when an allowedCheckCountryCodes entry is not a two-letter country code; the zod issues are in data
  • 401 Unauthorized
  • 403 Forbidden (global supporter, a customer outside the caller's scope, selfServiceNotAllowed or selfServiceQuotaReached)
  • 404 Customer not found
  • 403 targetHostMonitorLimitReached: the organization already has 100 monitors for this target host (see Limit per target host); allowDuplicate: true does not lift the limit
  • 403 targetHostPlatformLimitReached: the host already has 300 monitors across all Uptimeify customers (see Limit per target host)
  • 409 monitorAlreadyExists: this customer already has such a monitor (see Duplicates); allowDuplicate: true creates it anyway

Response

Returns the created DNS monitor object. See Error Codes for error responses.

On this page