> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Records

> RRsets, the apex, and the records the platform manages for you.

## Records

A record is an **RRset**: one name, one type, and a `values` array. Updating a
record replaces the value list wholesale.

<Tabs>
  <Tab title="Console">
    Open the zone from **DNS** and choose **Add Record**. Give it a **Name** —
    a subdomain like `www`, or `@` for the apex — pick a **Type**, and put one
    entry per line in **Values**. That list is the RRset. **TTL** is optional.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST /v1/zones/{zone_id}/records
    {
      "name": "www.example.com",
      "type": "A",
      "ttl": 300,
      "values": [
        { "content": "203.0.113.10" },
        { "content": "203.0.113.11" }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  There is no way to stage a value. `disabled: true` is refused — there is
  nowhere to keep a value that is not served, so it used to be accepted and
  then dropped, which reported success and lost the value. To take an address
  out of an RRset, remove it from `values`.
</Note>

<Warning>
  **A CNAME cannot share a name with any other record, and cannot sit at the
  zone apex.** The API refuses both, because the breakage is silent otherwise.

  The signer stamps each name's NSEC with a bitmap of the types that name
  holds. A CNAME beside an A yields a bitmap reading "CNAME and A", and a
  validating resolver treats that owner as bogus and answers SERVFAIL. The zone
  loads, the records look correct in the API, and the name simply stops
  resolving for anyone who validates. This is RFC 1034 §3.6.2 and RFC 2181
  §10.1.

  At the apex the conflict is unavoidable — the SOA and NS sets are always
  there — so point the apex at addresses with `A`/`AAAA` records.
</Warning>

## Pointing a zone apex at something

There is no `ALIAS` record type and no CNAME flattening. The apex takes
addresses, so what you put there has to be an address that stays put.

For anything on Basaltic it already is. A load balancer is reached through a
[floating IP](/networking/gateways) you allocate and hold, and that address does
not change for as long as you hold it — so an `A` record at the apex pointing at
it is stable. The same goes for an instance with a floating IP attached.

For a target somebody else runs — a CDN, a hosted front door — you are usually
given a hostname and no addresses. The addresses behind it are theirs to rotate,
and often differ by where the query came from, so there is nothing there that is
safe to pin at your apex. Put the `CNAME` on a subdomain such as `www`, and send
the apex to it with an HTTP redirect from whatever you do control.

## Platform-managed records

The SOA, the apex NS set, and the whole DNSSEC family are stamped and
maintained by this platform. They carry `managed: true`, and they cannot be
created, updated or deleted through the API.

**Listing records does not return them.** On a signed zone they outnumber your
own records — there is an `NSEC3` per name, plus the `DS` set, the `DNSKEY` and
the `SOA` — so returning them by default would mean paging through more of our
records than yours to find anything. The DNSSEC material worth having is on the
zone itself, under `dnssec`.

Pass `include_managed=true` to get the zone exactly as it is served:

```bash theme={null}
GET /v1/zones/{zone_id}/records?include_managed=true
```

That is what you want for a zone-diffing tool, and what the console's **show
managed** toggle uses. [Exporting a zone file](/dns/zone-files#exporting-a-zone-file) includes
the SOA and apex NS as any zone file does, and omits the DNSSEC records —
those sign keys held here and mean nothing anywhere else.