Skip to content

Create a DNS record

POST /api/v2/dns-zones/{id}/records

Create one DNS record in a zone. One record per call: the endpoint does not accept a top-level records array. Create does not replace old records. To change a website or mail record, read the zone first and use Update a DNS record. A record with the same type, name and value as an existing one is not added twice. The answer is then the existing record, with 201 as for a new one.

Use ALIAS, not CNAME, to point the apex at another hostname. A zone holds up to 200 customer-managed records, excluding SOA and NS. An A, AAAA, ALIAS or CNAME record replaces the Hostup parking page record at the same name. warnings[] is added when the name now has several A, AAAA or MX records worth a review.

Guides: Point a domain at your server, Set up MX, SPF, DKIM and DMARC, Change DNS records on many domains.

Authentication: An API key with the scope write:dns. About keys and scopes

Request

Path parameters

idstringrequired
The DNS zone ID. From GET /api/v2/dns-zones.

Body

typestring
The record type. There is no SPF type. SPF policies are TXT records whose value starts with v=spf1. One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA.
namestring
The record name relative to this DNS zone. Leave it out, or send @ or an empty string, for the zone root. Use a label such as www or _dmarc, not the full name www.example.com. Responses return full names. For an NS record, send only the subdomain label: in the zone example.com, name: "shop" delegates shop.example.com. That does not change the nameservers of example.com itself. Change domain nameservers does that.
valuestring
The target or content of the record. Send TXT values, SPF, DKIM and DMARC included, without surrounding quotes. The server adds the quotes. It splits long TXT values into DNS strings of at most 255 characters. Don’t split long TXT values yourself.
ttlinteger
Time to live in seconds. Default 3600. 60 to 86400.
priorityinteger
Priority. Required for MX and SRV records. Other types refuse it with 400. 0 to 65535.
weightinteger
SRV weight. Required for SRV records. Other types refuse it with 400. 0 to 65535.
portinteger
SRV port. Required for SRV records. Other types refuse it with 400. 1 to 65535.

Example

POST /api/v2/dns-zones/{id}/records
curl -X POST "https://cloud.hostup.se/api/v2/dns-zones/zone_01hxa3b4c5d6e7f8g9h0j1k2m3/records" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "A",
"name": "@",
"value": "192.0.2.1",
"ttl": 3600
}'

Responses

201 The created record.

Response 201
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3",
"type": "A",
"name": "example.com",
"value": "192.0.2.1",
"ttl": 3600
}
Response fields
idstring
typestring
One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.
namestring
The full name, such as _dmarc.example.com. The domain itself is example.com.
valuestring
ttlinteger
priorityinteger or null
Present only on MX and SRV records. null when the DNS server returned no priority.
weightinteger or null
Present only on SRV records. null when the DNS server returned no weight.
portinteger or null
Present only on SRV records. null when the DNS server returned no port.
proxiedboolean
Whether the record goes through the CDN proxy. Present only on A, AAAA and CNAME records when the proxy state is known.
proxyReasonstring
Why the proxy state of this record cannot be changed, ready to show. Present only when there is such a reason.
actionsobject
Action gates for this record. Present only when one applies.
canChangeProxyobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
warningsarray of object
Present only on a create response (POST /api/v2/dns-zones/{id}/records) when the record was added but the records with the same name need a look. Examples: several A records, AAAA records left over, several MX records.
codestring
One of same_name_address_records, same_name_ipv6_records, same_name_mx_records.
severitystring
One of warning.
messagestring
recordsarray of object
The existing records behind the warning. The record you created or changed is the main response.
idstring
typestring
namestring
valuestring
priorityinteger or null

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The record was refused. code is invalid_request. When the body itself is wrong, errors[].pointer names the field. Some refusals carry a general detail that names no rule: an IP address as an ALIAS or MX target, an NS record at the apex, an MX target without an A or AAAA address and a zone that is full. A root MX record while email forwarding is on returns mx_record_blocked_email_forwarding with requiresEmailForwardingDisable: true. Turn forwarding off with Turn domain email forwarding on or off.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is dns_zone_not_found.
409A CNAME clash. code is dns_conflict. A CNAME cannot share its name with other records. A name holds one CNAME. Delete the conflicting record or pick another name. Today a CNAME at the apex or one that points at an IP address gets this answer too.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
503The MX target could not be looked up right now. code is upstream_failed. Nothing was created. Retry shortly.