# 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.

URL: https://zrazu.com/en/docs/api-domains-dns/

All examples use the placeholder key `zr_live_...`. Substitute your own key from the [cabinet](https://vse.zrazu.com/team/api-keys/). General rules (sign-in, retries, errors, limits) are in the [API overview](https://zrazu.com/en/docs/api-overview.md).

## List domains

Needs the `domain.read` right.

```sh
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`.

```sh
# 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.

```sh
# 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:

```json
{
  "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.

```sh
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.

```sh
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:

```sh
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](https://zrazu.com/en/docs/api-keys.md).
- **`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.