Skip to main content

Monitoring API

Each watch checks one supported endpoint for one domain. Authenticate at https://api.edgedns.dev with your API key. Nonempty key permission lists need watches:read for reads and watches:write for writes. Monitoring data belongs to your organization.

Plan limits and scheduling

  • Free: 5 watches; minimum interval 1440 minutes.
  • Developer: 50 watches; minimum interval 30 minutes.
  • Pro: 250 watches; minimum interval 5 minutes.

Allowed interval_minutes values: 1, 5, 10, 30, 60, 120, 240, 480, 1440, 10080, 43200. Endpoint plan restrictions also apply. Paused watches still count toward the watch limit. Most analysis calls use one request unit per call. Uncached ping and traceroute probes use one unit per requested zone; cached results and status polls use one unit. Scheduled checks share your monthly request allowance. Enterprise availability is by arrangement; see pricing.

Creation queues an initial check; results arrive asynchronously. The first successful response establishes a baseline. Later checks can produce changes and alerts. Scheduling and notification delivery are asynchronous; the interval is a requested cadence.

Create a DNS watch

curl --request POST 'https://api.edgedns.dev/v1/watches' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "domain": "example.com",
  "endpoint_id": "dns-lookup",
  "endpoint_params": {
    "type": "A"
  },
  "interval_minutes": 1440,
  "alert_enabled": true,
  "alert_strategy": "json_diff",
  "alert_config": {},
  "notification_emails": [
    "ops@example.com"
  ]
}'
EndpointRequest and response
domain, endpoint_idRequired strings: domain up to 253 characters; endpoint_id must be one of the monitorable IDs below.
endpoint_paramsOptional object whose values are strings, for example {"type":"A"}. Use the selected endpoint’s parameter names.
interval_minutesRequired integer from the allowed values, at least the plan minimum.
alert_enabled, alert_strategyBoolean (default true); strategy is json_diff (default) or status_change.
alert_configOptional object, default {}. json_diff supports fields_to_watch (field-path array) and excluded_keys (leaf-key array). Timing and other volatile metadata are excluded automatically.
debounce_minutesInteger 1–240; default 5. Controls notification suppression for recent alerts of the same type; detected alerts can still be recorded.
notification_emailsUp to 10 email addresses, as an array or comma-separated string; defaults to [].
notification_webhooksUp to 5 HTTP or HTTPS URLs; defaults to [].
label, tagsOptional label up to 200 characters; up to 20 tags of at most 50 characters each.

PUT accepts these alert and scheduling fields plus is_active. It also accepts null to clear label; tags can be cleared with an empty array.

Watch routes

EndpointRequest and response
GET /v1/watchesList organization watches. Filters: domain, category, status (success/error/timeout), is_active (true/false). limit defaults to 50, maximum 200; offset defaults to 0. Returns data array, pagination, and meta.
POST /v1/watchesCreate one watch using the fields below. Returns data with id, domain, endpoint_id, endpoint_category and meta (HTTP 200).
GET /v1/watches/statsReturns total, active, healthy, errored, domains, limit, and tier inside data.
POST /v1/watches/batchJSON: domain and watches array (1–20 objects using the creation fields without domain). Returns data.domain and data.results with per-entry created, skipped, or error status; inspect every entry.
GET /v1/watches/:idRead one watch record belonging to your organization.
PUT /v1/watches/:idUpdate scheduling, alerts, recipients, label, tags, or is_active. Domain, endpoint_id, and endpoint_params cannot be changed; create a new watch for those changes.
DELETE /v1/watches/:idDelete the watch and associated history. Returns data.deleted = true.
POST /v1/watches/bulk-deleteJSON: ids array (1–100 watch IDs). Returns data.deleted count. Deletion also removes associated history.
POST /v1/watches/bulk-updateJSON: ids array (1–100), optional is_active and interval_minutes. Returns data.updated count.
GET /v1/watches/:id/snapshotsNewest checks first. limit defaults to 50 (maximum 200), offset defaults to 0. Returns data array with id, checked_at, status, duration_ms, response_hash, response_summary, error_message.
GET /v1/watches/:id/snapshots/:snapshotIdRead one snapshot including its stored response_full. Snapshot response_summary and response_full are JSON-encoded text fields; parse them before inspecting nested values.
GET /v1/watches/:id/snapshots/exportDownload CSV, up to 10,000 newest rows. Optional from and to are Unix timestamps in milliseconds. CSV is returned directly, outside the JSON envelope.
GET /v1/watches/:id/changesNewest detected changes first. limit defaults to 50 (maximum 200), offset defaults to 0. Returns data array.
GET /v1/watches/:id/alertsNewest triggered watch alerts first. limit defaults to 50 (maximum 200). Returns data array.

Watch detail rows expose stored booleans as 0/1 and JSON settings such as endpoint_params, alert_config, recipients, and tags as JSON text or null. History lists return data arrays and meta; only the watch list includes pagination totals. Timestamps in stored rows are Unix milliseconds.

Change alerts and webhooks

json_diff compares response values; status_change compares status, overall_status, reachable, and available fields when present. These strategies detect differences between checks. Certificate watches do not provide configurable days-before-expiry threshold alerts.

Webhooks receive POST application/json with alert_id, watch_id, domain, endpoint_id, alert_type, severity, message, triggered_at (ISO timestamp), and optional metadata. Delivery is best effort, with a 5-second timeout and one retry for network or server errors. Deduplicate by alert_id. Webhook payloads currently have no HMAC signature; use a private receiver URL and verify important alerts through the authenticated API.

400 indicates invalid input or an unsupported monitorable endpoint; 403 includes endpoint tier, minimum interval, and watch-limit restrictions; 404 indicates an unavailable watch or snapshot; 409 indicates a duplicate domain, endpoint, and parameter combination. See error handling.

Monitorable endpoint IDs

EndpointRequest and response
dns-lookupDNS Lookup — free or higher; /v1/dns/lookup
dns-dnssecDNSSEC Validation — free or higher; /v1/dns/dnssec
dns-propagationDNS Propagation — free or higher; /v1/dns/propagation
dns-mx-healthMX Health — developer or higher; /v1/dns/mx-health
dns-whoisWHOIS — free or higher; /v1/dns/whois
security-spfSPF Record — free or higher; /v1/security/spf
security-dmarcDMARC Policy — free or higher; /v1/security/dmarc
security-dkimDKIM — developer or higher; /v1/security/dkim
security-mta-stsMTA-STS — free or higher; /v1/security/mta-sts
security-bimiBIMI — free or higher; /v1/security/bimi
score-emailEmail Score — pro or higher; /v1/score/email
security-headersSecurity Headers — free or higher; /v1/security/headers
domain-sslSSL Certificate — free or higher; /v1/domain/ssl
domain-tls-versionTLS Version — free or higher; /v1/domain/tls-version
domain-hstsHSTS — free or higher; /v1/domain/hsts
domain-cert-chainCertificate Chain — developer or higher; /v1/domain/cert-chain
domain-ct-logsCT Logs — developer or higher; /v1/domain/ct-logs
domain-wafWAF Detection — developer or higher; /v1/domain/waf
score-securitySecurity Score — pro or higher; /v1/score/security
score-trustTrust Score — pro or higher; /v1/score/trust
domain-metaMeta Tags — free or higher; /v1/domain/meta
domain-robotsRobots.txt — free or higher; /v1/domain/robots
domain-sitemapSitemap — free or higher; /v1/domain/sitemap
domain-canonicalCanonical URL — free or higher; /v1/domain/canonical
domain-structured-dataStructured Data — developer or higher; /v1/domain/structured-data
domain-seo-auditSEO Audit — developer or higher; /v1/domain/seo-audit
domain-link-healthLink Health — developer or higher; /v1/domain/link-health
domain-redirectRedirect Chain — free or higher; /v1/domain/redirect
score-seoSEO Score — pro or higher; /v1/score/seo
domain-response-timeResponse Time — free or higher; /v1/domain/response-time
domain-compressionCompression — free or higher; /v1/domain/compression
domain-http-versionHTTP Version — free or higher; /v1/domain/http-version
domain-cacheCache Config — free or higher; /v1/domain/cache
domain-web-vitalsWeb Vitals — developer or higher; /v1/domain/web-vitals
domain-pagespeedPageSpeed — developer or higher; /v1/domain/pagespeed
domain-page-weightPage Weight — developer or higher; /v1/domain/page-weight
score-performancePerformance Score — pro or higher; /v1/score/performance
network-pingPing / Uptime — pro or higher; /v1/network/ping
domain-threatThreat Detection — developer or higher; /v1/domain/threat
domain-accessibilityAccessibility — developer or higher; /v1/domain/accessibility
domain-privacy-auditPrivacy Audit — developer or higher; /v1/domain/privacy-audit
score-complianceCompliance Score — pro or higher; /v1/score/compliance
domain-cdnCDN Detection — free or higher; /v1/domain/cdn
domain-dns-providerDNS Provider — free or higher; /v1/domain/dns-provider
Monitoring API — Watches, Change History & Webhooks | EdgeDNS