# Add Record
## Endpoint
`/api/zones/records/add`
## Method
GET (query parameters)
## Description
Adds a resource record for an authoritative zone. Supports all standard DNS record types plus proprietary types (ANAME, FWD, APP) and unknown record types (since v11.2).
## Authentication
Required. Session token from `login` or `createToken`.
## Permissions
- Zones: None
- Zone: Modify
## Common Parameters
| `token` | string | Yes | No | Session token from `login` or `createToken` |
| `domain` | string | Yes | No | The domain name of the zone to add the record |
| `zone` | string | No | No | The authoritative zone name. When unspecified, the closest authoritative zone is used |
| `node` | string | No | No | Node domain name for clustering. Only usable when Clustering is initialized |
| `type` | string | Yes | No | DNS resource record type. Supported: `A`, `AAAA`, `NS`, `CNAME`, `PTR`, `MX`, `TXT`, `SRV`, `DNAME`, `DS`, `SSHFP`, `TLSA`, `SVCB`, `HTTPS`, `URI`, `CAA`, `ANAME`, `FWD`, `APP`, `RP`, `NAPTR`, plus unknown types |
| `ttl` | integer | No | No | TTL in seconds. Defaults to server setting when not specified |
| `overwrite` | boolean | No | No | When `true`, overwrites existing RRset for the selected type. Default: `false` (appends to existing RRset) |
| `comments` | string | No | No | Comments for the resource record |
| `expiryTtl` | integer | No | No | Auto-delete the record after this many seconds since last modified time |
## Per-Record-Type Parameters
### A / AAAA
| `ipAddress` | string | Yes | IP address for the record. Special value `request-ip-address` uses the API request's source IP (useful for dynamic DNS) |
| `ptr` | boolean | No | When `true`, also creates a reverse PTR record for the IP address |
| `createPtrZone` | boolean | No | When `true`, creates the reverse zone for the PTR record if it does not exist |
| `updateSvcbHints` | boolean | No | When `true`, updates SVCB/HTTPS records in the zone that have Automatic Hints enabled and match the current record's domain name |
### NS
| `nameServer` | string | Yes | The name server domain name |
| `glue` | string | No | Glue address(es) for the name server |
### CNAME
| `cname` | string | Yes | The CNAME domain name |
### PTR
| `ptrName` | string | Yes | The PTR domain name |
### MX
| `exchange` | string | Yes | The exchange domain name |
| `preference` | integer | Yes | The MX preference value |
### TXT
| `text` | string | Yes | The text data for the TXT record |
| `splitText` | boolean | No | When `true`, splits text on newline characters into multiple character-strings |
### RP
| `mailbox` | string | Yes | Email address for the RP record |
| `txtDomain` | string | Yes | TXT record domain name for the RP record |
### SRV
| `priority` | integer | Yes | SRV priority value |
| `weight` | integer | Yes | SRV weight value |
| `port` | integer | Yes | SRV port value |
| `target` | string | Yes | SRV target domain name |
### NAPTR
| `naptrOrder` | integer | Yes | NAPTR order value |
| `naptrPreference` | integer | Yes | NAPTR preference value |
| `naptrFlags` | string | Yes | NAPTR flags value |
| `naptrServices` | string | Yes | NAPTR services value |
| `naptrRegexp` | string | Yes | NAPTR regexp value |
| `naptrReplacement` | string | Yes | NAPTR replacement value |
### DNAME
| `dname` | string | Yes | The DNAME domain name |
### DS
| `keyTag` | integer | Yes | DS key tag |
| `algorithm` | string | Yes | Valid: `RSAMD5`, `DSA`, `RSASHA1`, `DSA-NSEC3-SHA1`, `RSASHA1-NSEC3-SHA1`, `RSASHA256`, `RSASHA512`, `ECC-GOST`, `ECDSAP256SHA256`, `ECDSAP384SHA384`, `ED25519`, `ED448` |
| `digestType` | string | Yes | Valid: `SHA1`, `SHA256`, `GOST-R-34-11-94`, `SHA384` |
| `digest` | string | Yes | Hex string value |
### SSHFP
| `sshfpAlgorithm` | string | Yes | Valid: `RSA`, `DSA`, `ECDSA`, `Ed25519`, `Ed448` |
| `sshfpFingerprintType` | string | Yes | Valid: `SHA1`, `SHA256` |
| `sshfpFingerprint` | string | Yes | Hex string value |
### TLSA
| `tlsaCertificateUsage` | string | Yes | Valid: `PKIX-TA`, `PKIX-EE`, `DANE-TA`, `DANE-EE` |
| `tlsaSelector` | string | Yes | Valid: `Cert`, `SPKI` |
| `tlsaMatchingType` | string | Yes | Valid: `Full`, `SHA2-256`, `SHA2-512` |
| `tlsaCertificateAssociationData` | string | Yes | X509 certificate in PEM format or hex string |
### SVCB / HTTPS
| `svcPriority` | integer | Yes | Priority value |
| `svcTargetName` | string | Yes | Target domain name |
| `svcParams` | string | Yes | Pipe-separated key-value list. Example: `alpn\|h2,h3\|port\|53443`. Set to `false` to clear |
| `autoIpv4Hint` | boolean | No | Enable Automatic Hints for `ipv4hint` in svcParams |
| `autoIpv6Hint` | boolean | No | Enable Automatic Hints for `ipv6hint` in svcParams |
### URI
| `uriPriority` | integer | Yes | URI priority value |
| `uriWeight` | integer | Yes | URI weight value |
| `uri` | string | Yes | The URI value |
### CAA
| `flags` | integer | Yes | CAA flags value |
| `tag` | string | Yes | CAA tag value |
| `value` | string | Yes | CAA value |
### ANAME
| `aname` | string | Yes | The ANAME domain name (proprietary type) |
### FWD (Forwarder - proprietary)
| `protocol` | string | Yes | Valid: `Udp`, `Tcp`, `Tls`, `Https`, `Quic` |
| `forwarder` | string | Yes | Forwarder address. Special value `this-server` forwards internally to the DNS server |
| `forwarderPriority` | integer | No | Priority value. Lower value = higher priority. Same priority = concurrent query |
| `dnssecValidation` | boolean | No | Whether DNSSEC validation must be done. Default: `false` |
| `proxyType` | string | No | Valid: `NoProxy`, `DefaultProxy`, `Http`, `Socks5`. Default: `DefaultProxy` |
| `proxyAddress` | string | No | Proxy server address (used when `proxyType` is configured) |
| `proxyPort` | integer | No | Proxy server port (used when `proxyType` is configured) |
| `proxyUsername` | string | No | Proxy server username (used when `proxyType` is configured) |
| `proxyPassword` | string | No | Proxy server password (used when `proxyType` is configured) |
### APP (DNS App - proprietary)
| `appName` | string | Yes | Name of the DNS app |
| `classPath` | string | Yes | Class path for the DNS app |
| `recordData` | string | No | App-specific record data |
### Unknown Record Types
| `rdata` | string | Yes | Hex string or colon-separated hex string for unsupported record types |
## Response Fields
| `status` | string | `"ok"` on success |
| `response.zone.name` | string | Zone name |
| `response.zone.type` | string | Zone type (e.g., `Primary`) |
| `response.zone.internal` | boolean | Whether the zone is internal |
| `response.zone.dnssecStatus` | string | DNSSEC signing status |
| `response.zone.disabled` | boolean | Whether the zone is disabled |
| `response.addedRecord.disabled` | boolean | Whether the record is disabled |
| `response.addedRecord.name` | string | Record domain name |
| `response.addedRecord.type` | string | Record type |
| `response.addedRecord.ttl` | integer | TTL in seconds |
| `response.addedRecord.rData` | object | Record-type-specific data |
| `response.addedRecord.dnssecStatus` | string | DNSSEC status of the record |
| `response.addedRecord.lastUsedOn` | string | Timestamp of last use |
## Conditional Logic Notes
1. **`ipAddress` is required when `type` is `A` or `AAAA`**. It accepts the special value `request-ip-address` to use the HTTP request source IP.
2. **`ptr`, `createPtrZone`, `updateSvcbHints`** are only meaningful for `A` and `AAAA` records; ignored for other types.
3. **`nameServer` is required when `type` is `NS`**. `glue` is optional for NS records only.
4. **`cname` is required when `type` is `CNAME`**. Only one CNAME can exist per domain name.
5. **`ptrName` is required when `type` is `PTR`**.
6. **Both `exchange` and `preference` are required when `type` is `MX`**.
7. **`text` is required when `type` is `TXT`**. `splitText` is optional and only applies to TXT.
8. **Both `mailbox` and `txtDomain` are required when `type` is `RP`**.
9. **All four SRV fields (`priority`, `weight`, `port`, `target`) are required when `type` is `SRV`**.
10. **All six NAPTR fields (`naptrOrder`, `naptrPreference`, `naptrFlags`, `naptrServices`, `naptrRegexp`, `naptrReplacement`) are required when `type` is `NAPTR`**.
11. **`dname` is required when `type` is `DNAME`**.
12. **All four DS fields (`keyTag`, `algorithm`, `digestType`, `digest`) are required when `type` is `DS`**.
13. **All three SSHFP fields (`sshfpAlgorithm`, `sshfpFingerprintType`, `sshfpFingerprint`) are required when `type` is `SSHFP`**.
14. **All four TLSA fields are required when `type` is `TLSA`**.
15. **`svcPriority`, `svcTargetName`, and `svcParams` are required when `type` is `SVCB` or `HTTPS`**. `autoIpv4Hint` and `autoIpv6Hint` are optional and only apply to SVCB/HTTPS.
16. **All three URI fields (`uriPriority`, `uriWeight`, `uri`) are required when `type` is `URI`**.
17. **All three CAA fields (`flags`, `tag`, `value`) are required when `type` is `CAA`**.
18. **`aname` is required when `type` is `ANAME`**.
19. **Both `protocol` and `forwarder` are required when `type` is `FWD`**. Proxy parameters are only used when `proxyType` is set to `Http` or `Socks5`.
20. **Both `appName` and `classPath` are required when `type` is `APP`**. `recordData` is optional and app-specific.
21. **`rdata` is used for unknown/unsupported record types only**.
22. **`overwrite=true`** replaces the entire RRset; `overwrite=false` (default) adds to the existing set. This distinction matters for types that allow multiple records (A, AAAA, NS, MX, TXT, SRV, etc.).
23. **SOA records cannot be added** via this endpoint -- SOA is created automatically with the zone.
24. The `type` parameter value is case-sensitive in the URL but the docs list uppercase values.
## Edge Cases
- The `request-ip-address` special value for `ipAddress` enables dynamic DNS use cases where the client's IP is automatically used.
- The `this-server` special value for `forwarder` in FWD records causes internal forwarding within the DNS server itself.
- `svcParams` uses a pipe-separated format (`key|value|key|value`), not standard query string encoding.
- `tlsaCertificateAssociationData` accepts either PEM-encoded X509 certificates OR hex strings -- dual format.
- `overwrite=true` is destructive: it replaces the entire record set for that type, not just a single record.
- The API docs mark the SVCB/HTTPS type parameter value as `SCVB` in some places (likely a typo in the docs; the actual type value is `SVCB`).
- Unknown record types are supported since v11.2 using the `rdata` parameter with hex-encoded data.
- `forwarderPriority` for FWD records: forwarders with the same priority are queried concurrently; lower numeric values have higher priority.