Health, forwarding and users over the API

This page covers the operational endpoints with curl examples. All need a bearer token; see the API overview.

Health checks

# List
curl -sk https://dtm.internal:8443/api/v1/healthchecks \
  -H "Authorization: Bearer $DTM_TOKEN"

# Create a monitor-only check (status metrics, no DNS effect)
curl -sk -X POST https://dtm.internal:8443/api/v1/healthchecks \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-check",
    "protocol": "http",
    "target": "10.0.1.10:80",
    "interval_seconds": 15,
    "timeout_seconds": 5,
    "failure_threshold": 3,
    "http_config": {"path": "/healthz", "expected_status": [200]}
  }'

A check created directly on /api/v1/healthchecks is monitor-only: it probes and reports status (the dtm_health_check_status metric and the Health Checks page) but never gates any record’s DNS answers. To make answers health-aware, put a health_check_template on the record instead; see health checks.

For HTTP/HTTPS checks, http_config can also carry authentication (headers, oauth2, mtls, managed_identity) to probe secured backends; see authenticated health probes.

Script checks ("protocol": "script", admin-only and disabled by default) carry a script_config with the command and args to run. An optional script_config.timeout_seconds overrides the top-level probe timeout for the script run; like the top-level value, it must not exceed interval_seconds. In the audit log, args values are masked (they routinely carry credentials) while the command itself is recorded verbatim.

Check current status:

# One check
curl -sk https://dtm.internal:8443/api/v1/healthchecks/<id>/status \
  -H "Authorization: Bearer $DTM_TOKEN"

# All checks on this node
curl -sk https://dtm.internal:8443/api/v1/health/status \
  -H "Authorization: Bearer $DTM_TOKEN"

Forwarders and stub zones

# Default forwarder (where unmatched queries go)
curl -sk -X PUT https://dtm.internal:8443/api/v1/forwarders/default \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"upstreams": ["168.63.129.16"], "enabled": true}'

# Conditional forwarder for one domain
curl -sk -X POST https://dtm.internal:8443/api/v1/forwarders \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"domain": "corp.contoso.com.", "upstreams": ["10.0.0.1:53"], "comment": "AD DNS"}'

# Stub zone
curl -sk -X POST https://dtm.internal:8443/api/v1/stub-zones \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"domain": "partner.local.", "hints": ["10.5.0.1:53"]}'

See forwarders and stub zones for the concepts.

Blocklist

curl -sk -X PUT https://dtm.internal:8443/api/v1/blocklist \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["doubleclick.net", "trackers.example"]}'

Users

User management requires the admin role. See users and access.

# List users (password hashes are stripped)
curl -sk https://dtm.internal:8443/api/v1/users \
  -H "Authorization: Bearer $DTM_TOKEN"

# Create a user (password >= 16 chars; role admin|editor|readonly)
curl -sk -X POST https://dtm.internal:8443/api/v1/users \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "long-enough-password-1234", "role": "editor"}'

# Update a user's role / enabled / password
curl -sk -X PUT https://dtm.internal:8443/api/v1/users/<id> \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{"role": "readonly", "enabled": true}'

Cluster membership

# List nodes with status, region, address
curl -sk https://dtm.internal:8443/api/v1/nodes \
  -H "Authorization: Bearer $DTM_TOKEN"

# This node's own info
curl -sk https://dtm.internal:8443/api/v1/nodes/self \
  -H "Authorization: Bearer $DTM_TOKEN"

Audit log

curl -sk "https://dtm.internal:8443/api/v1/audit?limit=100" \
  -H "Authorization: Bearer $DTM_TOKEN"

Optional filters: user_id, user_name, resource, resource_id, action, plus from / to time bounds (RFC 3339 or YYYY-MM-DD). limit defaults to 50. Readable by editor and admin. GET /api/v1/audit/export streams the same data as NDJSON for archival; like the other export and backup GETs it requires the X-DTM-CSRF: 1 header, so include it in any scheduled job:

curl -sk https://<dtm>:8443/api/v1/audit/export \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1"

The stored audit log is bounded: entries beyond the configured retention are pruned oldest-first (see audit log retention). If you need audit evidence beyond that window, schedule the NDJSON export to immutable storage you control, for example a nightly job writing to an Azure Storage container with an immutability policy.

Stats

curl -sk https://dtm.internal:8443/api/v1/stats \
  -H "Authorization: Bearer $DTM_TOKEN"
# {"zones": 5, "records": 42, "nodes": 3, "users": 2}

For the complete endpoint list, see the endpoint reference.