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.
• 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:

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.

Lifecycle#

• 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 — create, update, delete zones.
• Managing Records — the full record CRUD surface.
• Reverse Zones — CIDR-based zone creation and PTR records.