API and MCP

Domains and DNS through the API — examples

Examples of ZRAZU API requests: list domains, monitoring, read a DNS zone, change records, create a zone and check delegation.

All examples use the placeholder key zr_live_.... Substitute your own key from the cabinet. General rules (sign-in, retries, errors, limits) are in the API overview.

List domains

Needs the domain.read right.

curl -H "Authorization: Bearer zr_live_..." "https://api.zrazu.com/v1/domains?limit=100"

For each domain the response has name, expires_at, autorenew, transfer_lock, contact_lock, frozen. If there are more pages, pass next from the response as after.

Monitoring

Rights monitor.read and monitor.edit.

# monitoring state
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/monitoring

# put up to 100 names under watch per call
curl -X POST https://api.zrazu.com/v1/monitoring \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"names": ["example.com.ua", "example.net"]}'

# take off watch
curl -X DELETE https://api.zrazu.com/v1/monitoring/example.net \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

In the response to an add, the skipped field lists the lines that could not be accepted, with a reason: a typo does not vanish silently.

Read a DNS zone

Needs the dns.read right.

# list of zones
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/dns/zones

# records of one zone
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/dns/zones/example.com.ua

Response to the second request:

{
  "name": "example.com.ua",
  "serial": 12,
  "records": [
    { "name": "@", "type": "A", "ttl": 300, "content": "203.0.113.10", "prio": null },
    { "name": "www", "type": "CNAME", "ttl": 300, "content": "example.com.ua.", "prio": null }
  ]
}

Record names are relative to the zone: @ for the zone itself, www for www.example.com.ua. You will need serial to make a change.

Change zone records

Needs the dns.edit right. The flow: read the zone, change the list, send it back whole together with base_serial — the number you read.

curl -X PUT https://api.zrazu.com/v1/dns/zones/example.com.ua \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "base_serial": 12,
    "summary": "new site server",
    "records": [
      { "name": "@", "type": "A", "ttl": 300, "content": "203.0.113.20" },
      { "name": "www", "type": "CNAME", "ttl": 300, "content": "example.com.ua." }
    ]
  }'
  • The list must contain all records of the zone, not only the changed ones: what you do not send is deleted.
  • A zone holds up to 500 records.
  • If the zone changed between your read and write, the answer is 409: read the zone again and repeat.
  • Before saving, the zone is checked the same way as in the cabinet: an error in a record gives 409 with no changes, warnings come back in the warnings field.
  • After a change, owners and administrators get an email, and the change stays in the zone history under the key's name. At most 60 changes per hour per key.

New zone and delegation check

Needs the dns.zone_create right — only for a key covering all zones of the organization.

curl -X POST https://api.zrazu.com/v1/dns/zones \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com.ua", "import_current": true}'
  • For a domain registered with ZRAZU, the zone is turned on at our nameservers. With import_current: true the records that currently answer at the previous provider are carried over.
  • For a domain at another registrar a request is created. Set the nameservers from the response at that registrar, then start the check:
curl -X POST https://api.zrazu.com/v1/dns/zones/example.com.ua/verify \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

Answer 202 means the check has started. Call GET /v1/dns/zones later to see the status.

If it didn't work

  • `403 right_missing`. The key lacks the needed right — see API keys.
  • `403 out_of_scope`. The domain is outside the key's domain list.
  • `404 not_found`. The zone does not exist, is not yours or is outside the key's domains — the answer is the same.
  • `409` on `PUT`. The zone changed after you read it, or the records contain an error. Read the zone again and repeat with the new base_serial.
  • `503 dns_closed`. ZRAZU DNS temporarily doesn’t accept changes; try later.
  • `409 zone_exists`. The zone for this domain already exists.
  • `429`. Too many changes: wait Retry-After seconds.

This page in Markdown