--- title: "Add a record under a hostname" method: POST path: "/v1/hostnames/{id}/records" --- # Add a record under a hostname `POST /v1/hostnames/{id}/records` ## Request - Base URL: `https://dnsmint.com/api` - URL: `https://dnsmint.com/api/v1/hostnames/{id}/records` - Auth: HTTP bearer Adds one TXT, TLSA, CAA, MX, SRV, SSHFP, HTTPS or SVCB record. Up to 10 records per hostname, on every plan - a ceiling against a hostname becoming a zone, since DNS egress follows hostnames. To change a value, PUT the record's id - one call, and the id survives. Deleting and re-adding costs two writes and leaves a window where the name resolves wrong. TTL is fixed at 300s. A TXT value longer than 255 bytes is split into several character-strings, which is what the wire format requires and what every client concatenates back. TLSA returns 409 until the domain is signed and its DS is live. A TLSA record says which certificate to trust, and in an unsigned zone anything that can spoof the answer can substitute its own binding - so publishing one would point clients at a certificate nobody vouched for. CAA replaces the domain's policy for that hostname rather than adding to it. A CA reads the nearest ancestor with a CAA record set and ignores the rest, so publishing one here takes over which CAs may issue for your name - including excluding ours. Delete it and the domain's policy applies again. That is how CAA works and we serve what you write; we do not merge it with ours. A SRV record's name must be `_._`, the way a TLSA record's must be `_._` - RFC 2782 puts them in the owner name and a client only looks there. ## Path parameters - `id` string, required ## Request body - CreateRecordRequest - `type` 'TXT' | 'TLSA' | 'CAA' | 'MX' | 'SRV' | 'SSHFP' | 'HTTPS' | 'SVCB', required: A hostname's address is set by PUT on the hostname itself, and CAA is operator policy, so neither is accepted here. - `name` string: Label under the hostname. Omit for a record on the hostname itself. `_acme-challenge` is reserved: certificate issuance publishes there. TLSA requires `_._`, e.g. `_443._tcp` - RFC 6698 puts the port and protocol in the owner name and a client looks nowhere else. - `text` union: TXT only. A string, or a list of strings to send as-is. No control characters. RFC 1035 caps each character-string at 255 bytes and a TXT record holds a sequence of them which the client concatenates, so a longer value is split for you at 255 and a list you supply is sent unchanged, each string checked against that limit. 2048 bytes in total. This is how a 2048-bit DKIM key or a full MCP discovery record is carried. - string - string[] - `usage` 0 | 1 | 2 | 3: TLSA certificate usage. 3 is DANE-EE. - `selector` 0 | 1: TLSA selector. 0 full certificate, 1 SubjectPublicKeyInfo. - `matching_type` 0 | 1 | 2: TLSA matching type. 0 full, 1 SHA-256, 2 SHA-512. The association length must match: 64 hex digits for SHA-256, 128 for SHA-512. - `association` string: TLSA certificate-association data, lowercase hex, no separators. - `preference` integer: MX only. Lower is preferred. 0 with an exchange of `.` is the RFC 7505 null MX, which says this name accepts no mail. - `exchange` string: MX only. The mail host. `.` is the root, for the null MX. - `priority` integer: SRV: lower is tried first. HTTPS and SVCB: 1 or above. 0 is AliasMode, which we do not serve, because it aliases a zone apex and a hostname is never an apex. - `weight` integer: SRV only. Relative share among targets of equal priority. - `port` integer: SRV only. The port the service listens on. - `target` string: SRV: the host offering the service, or `.` to say it is decidedly not offered here. HTTPS and SVCB: the endpoint, or `.` for this name, which is the ordinary case. - `algorithm` integer: SSHFP only. 1 RSA, 2 DSA, 3 ECDSA, 4 Ed25519, 6 Ed448. - `fptype` integer: SSHFP only. 1 for SHA-1, 2 for SHA-256. The fingerprint length follows from it. - `fingerprint` string: SSHFP only. Lowercase hex, no separators. 40 digits for SHA-1, 64 for SHA-256. - `params` object: HTTPS and SVCB only. RFC 9460 service parameters: `alpn` (list, e.g. h2 or h3), `noDefaultAlpn` (boolean, only meaningful with `alpn`), `port`, `ipv4hint` and `ipv6hint` (lists of literal addresses), `ech` (base64), and `mandatory` (the parameter names a client must understand, which may not name itself or a parameter this record does not set). Send them as fields; we emit them in the ascending key order the wire format requires. ## Response `201` Created - HostRecord - `id` string: Pass this to DELETE. - `name` string - `type` 'TXT' | 'TLSA' | 'CAA' | 'MX' | 'SRV' | 'SSHFP' | 'HTTPS' | 'SVCB' - `ttl` integer - `data` object: The record's fields: `text` for TXT; `usage`, `selector`, `matching_type` and `association` for TLSA. ## Other responses - `400`: Unusable type, name or rdata - `401`: Missing or invalid API key - `403`: Key lacks hostnames:write, or is narrowed to another hostname - `404`: Hostname not found - `409`: At the 10-record limit, the hostname is frozen, or TLSA on an unsigned zone - `429`: Rate limited --- [API](https://skmtc.dev/dnsmint/apis/dnsmint-api.md) · [All operations](https://skmtc.dev/dnsmint/apis/dnsmint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dnsmint/apis/dnsmint-api/revisions/98fb1f87725a?raw)