---
title: Zones and Records
path: concepts/zones-and-records
status: published
---

# Zones and Records

The foundational concepts. Everything else in the API is about creating, managing, or delegating access to these two resources.

## Zone

A **zone** (also called a "domain" in the API for historical reasons) is a DNS zone of authority — a section of the DNS hierarchy for which a nameserver has complete answers. `example.com` is a zone. `10.in-addr.arpa` is a zone. `subdomain.example.com` *can* be a zone if you've delegated it.

In ScaiDNS, a zone has:

- **Name.** The zone apex. `example.com`, `eu.example.com`, `10.in-addr.arpa`.
- **Type.** One of:
    - `primary` — a forward zone you own and edit directly.
    - `secondary` — a slave zone transferred from another authoritative server.
    - `reverse_ipv4` — an IPv4 reverse zone (`*.in-addr.arpa`).
    - `reverse_ipv6` — an IPv6 reverse zone (`*.ip6.arpa`).
- **Status.** One of:
    - `pending_validation` — created but not yet proven to be yours.
    - `active` — live and serving DNS.
    - `inactive` — soft-disabled without being deleted.
    - `deleted` — soft-deleted, recoverable until purged.
- **Default TTL.** Seconds. Applied to records that don't specify their own TTL.
- **DNSSEC enabled.** Boolean. See [DNSSEC](./dnssec.md).
- **Tenant.** Every zone belongs to exactly one tenant.

Zones are identified by UUID. Use that UUID in all record, access-grant, and DNSSEC API calls.

## Record

A **record** is a single DNS RRdata entry. ScaiDNS stores records with these fields:

- **Name.** The leaf name relative to the zone (`www`, `mail`) or `@` for the zone apex. Returned in read responses as a fully-qualified `www.example.com.`.
- **Type.** Uppercase DNS record type. `A`, `AAAA`, `MX`, `CNAME`, `TXT`, `NS`, `SRV`, `PTR`, `SOA`, `CAA`, `SSHFP`, `TLSA`, `DNAME`, `NAPTR`, `DS`, `ALIAS`.
- **Content.** The record data, formatted per PowerDNS conventions. For simple types this matches zone-file syntax: `192.0.2.1` for `A`, `2001:db8::1` for `AAAA`, `mail.example.com.` for `CNAME`. For MX, content is `priority target` — `10 mail.example.com.`.
- **TTL.** Seconds. Omit to use the zone's `default_ttl`.
- **Disabled.** Boolean. Disabled records are stored but excluded from DNS responses. Useful for maintenance windows.

### Supported types

The API accepts these types; validation is strict per RFC requirements:

| Type | Purpose | Content example |
|------|---------|-----------------|
| `A` | IPv4 address | `192.0.2.1` |
| `AAAA` | IPv6 address | `2001:db8::1` |
| `CNAME` | Alias | `target.example.com.` |
| `MX` | Mail exchanger | `10 mail.example.com.` |
| `NS` | Nameserver delegation | `ns1.example.com.` |
| `TXT` | Arbitrary text | `"v=spf1 -all"` |
| `SOA` | Zone authority | Usually managed automatically |
| `SRV` | Service locator | `10 5 5060 sipserver.example.com.` |
| `PTR` | Reverse pointer | `host.example.com.` |
| `CAA` | Certificate authority authorization | `0 issue "letsencrypt.org"` |
| `SSHFP` | SSH public key fingerprint | `1 1 <hex>` |
| `TLSA` | DANE TLS binding | `3 1 1 <hex>` |
| `DNAME` | Subtree alias | `target.example.com.` |
| `ALIAS` | Apex-compatible CNAME | `target.example.com.` |

Get the authoritative list from `GET /api/v1/domains/types`.

### Name conventions

Sending `"name": "www"` on a zone `example.com` creates `www.example.com`. Sending `"name": "@"` creates a record at the zone apex (`example.com` itself). Sending the full FQDN `"name": "www.example.com"` also works — ScaiDNS normalizes both forms.

Read responses include both forms: `name` is the FQDN, `display_name` is the relative name.

### System records

Every active zone has two record types automatically managed:

- **SOA.** Start-of-authority. Created on zone creation, updated when zone data changes (serial bumps). You can read it via `GET /api/v1/domains/{id}/soa` but don't edit it directly unless you know why.
- **NS.** Delegation of the zone to its own nameservers. Created from platform config. Editable if you need custom NS records but usually left alone.

By default, listings exclude SOA and NS. Pass `?include_system=true` to see them.

## Forward vs reverse

**Forward zones** map names to addresses. You ask "what is the IP of `www.example.com`" and get an A or AAAA answer.

**Reverse zones** map addresses to names. You ask "what name is `192.0.2.10`" and get a PTR answer from a zone named `10.2.0.192.in-addr.arpa`.

ScaiDNS treats reverse zones as first-class with a dedicated API that accepts CIDR input and handles the awkward `in-addr.arpa` naming for you. See [Reverse Zones](../tutorials/reverse-zones.md).

## Lifecycle

```mermaid
stateDiagram-v2
    [*] --> pending_validation : create
    pending_validation --> active : validate
    active --> deleted : delete
    deleted --> active : restore
```

- **Create.** Row inserted in MariaDB with status `pending_validation`. No PowerDNS zone yet.
- **Validate.** TXT or NS validation proves ownership. On success, PowerDNS zone is created and status flips to `active`.
- **Edit.** Add, update, delete records freely while active.
- **Delete.** Soft-delete by default — status `deleted`, hidden from listings, recoverable via `POST /{id}/restore`. Hard delete (`?hard=true`) removes the row and PowerDNS zone permanently.

## Identifiers

- **Domain ID.** UUID. Stable for the lifetime of the zone.
- **Record ID.** UUID. Stable for the lifetime of the record — if you update it, the ID stays. If you delete and recreate, you get a new ID.
- **PowerDNS zone ID.** Internal. Not surfaced in the API.

## What's next

- [Managing Domains](../tutorials/managing-domains.md) — create, update, delete zones.
- [Managing Records](../tutorials/managing-records.md) — the full record CRUD surface.
- [Reverse Zones](../tutorials/reverse-zones.md) — CIDR-based zone creation and PTR records.