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
idstringrequiredGET /api/v2/dns-zones.Body
typestringTXT records whose value starts with v=spf1. One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA.namestring@ 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.valuestringttlintegerpriorityintegerweightintegerportintegerExample
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 }'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": "AAAA", "name": "@", "value": "2001:db8::1", "ttl": 3600 }'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": "CNAME", "name": "www", "value": "target.example.com", "ttl": 3600 }'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": "ALIAS", "name": "@", "value": "target.example.com", "ttl": 3600 }'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": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com", "ttl": 3600 }'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": "MX", "name": "@", "value": "mail.example.com", "priority": 10, "ttl": 3600 }'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": "SRV", "name": "_sip._tcp", "value": "sip.example.com", "priority": 10, "weight": 5, "port": 5060, "ttl": 3600 }'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": "CAA", "name": "@", "value": "0 issue \"letsencrypt.org\"", "ttl": 3600 }'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": "TLSA", "name": "_443._tcp", "value": "3 1 1 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "ttl": 3600 }'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": "NS", "name": "acme", "value": "ns1.acme.example.net", "ttl": 3600 }'Responses
201 The created record.
{ "id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3", "type": "A", "name": "example.com", "value": "192.0.2.1", "ttl": 3600}Response fields
idstringtypestringA, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.namestring_dmarc.example.com. The domain itself is example.com.valuestringttlintegerpriorityinteger or nullnull when the DNS server returned no priority.weightinteger or nullnull when the DNS server returned no weight.portinteger or nullnull when the DNS server returned no port.proxiedbooleanproxyReasonstringactionsobjectcanChangeProxyobjectallowedbooleanreasonstring or nullcodestring or nullwarningsarray of objectPOST /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.codestringsame_name_address_records, same_name_ipv6_records, same_name_mx_records.severitystringwarning.messagestringrecordsarray of objectidstringtypestringnamestringvaluestringpriorityinteger or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The 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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is dns_zone_not_found. |
| 409 | A 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. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 503 | The MX target could not be looked up right now. code is upstream_failed. Nothing was created. Retry shortly. |