Create DNS record

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

Create one DNS record after server-side validation.

Get the zone id from GET /api/v2/dns-zones data[].id; use GET /api/v2/dns-zones/{id}/records first when the user expects an existing website or mail record to be changed.

Create does not replace old records and this endpoint does not accept a top-level records array; call it once per DNS record.

The request name is relative to the selected zone: send @ or an empty string for the zone root and labels such as www, _dmarc, or _sip._tcp for subdomains; do not send the full FQDN such as www.example.com.

Responses may return normalized FQDN names and may include warnings[] when the create succeeds but leaves multiple same-name A/AAAA/MX records that should be reviewed.

Use ALIAS, not CNAME, when the zone root should point at another hostname.

TXT values, including SPF policies, must be sent as one unquoted value; the server handles safe quoting and splits long TXT-like values into DNS protocol strings of at most 255 characters.

Create SPF policies as TXT records with a value starting v=spf1.

A zone can contain up to 200 customer-managed records, excluding SOA and NS records.

NS records here delegate a subdomain only: in zone xyz.se, { "type": "NS", "name": "acme", "value": "ns1.acme.example.net" } delegates acme.xyz.se.

This does not change authoritative nameservers for xyz.se; use POST /api/v2/domains/{id}/nameservers for that.

The API rejects duplicates, duplicate MX priorities, CNAME conflicts, root CNAMEs, IP addresses in CNAME/ALIAS/MX/NS targets, mismatched TXT quotes, invalid A/AAAA values, invalid SRV/TLSA parts, and root NS changes before the zone can be broken. 429 responses include Retry-After seconds plus X-RateLimit-* headers.

Domains & DNS DNS

Authentication

Required API scope: write:dns

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Path Parameters

id string required Example: zone_01hxa3b4c5d6e7f8g9h0j1k2m3

Public DNS zone ID. Get it from GET /api/v2/dns-zones data[].id. Do not invent this value; use the exact ID returned by the referenced API response.

Headers

Authorization Bearer <token>
Accept application/json
Content-Type application/json

Body

required
application/json
type string · enum · Example: TXT
A
AAAA
CNAME
ALIAS
MX
TXT
SRV
CAA
NS
TLSA
name string · Example: _dmarc

Record owner name relative to this DNS zone. Use @ or an empty string for the zone root; use labels such as www or _dmarc, not the full FQDN www.example.com. Responses may return normalized FQDN names. For NS records, send the subdomain label only: in zone xyz.se, name: "acme" delegates acme.xyz.se. This does not change authoritative nameservers for xyz.se; use /api/v2/domains/{id}/nameservers for that.

value string · Example: v=DMARC1; p=none; rua=mailto:dmarc@example.com

Record target or content. Send TXT values, including SPF/DKIM/DMARC policy values, without surrounding quotes; the server applies DNS-safe quoting and splits long TXT-like values into DNS protocol strings of at most 255 characters. Do not pre-split long TXT values.

ttl integer · min: 60 · max: 86400 · Example: 3600

TTL in seconds, from 60 to 86400. Send as a JSON number; integer-like strings are tolerated for tool adapters.

priority integer · min: 0 · max: 65535 · Example: 10

MX or SRV priority. Send as a JSON number; integer-like strings are tolerated for tool adapters.

weight integer · min: 0 · max: 65535 · Example: 0
port integer · min: 1 · max: 65535 · Example: 443

Responses

201 Created DNS record.
id string · Example: drr_01hxa3b4c5d6e7f8g9h0j1k2m3
type string · enum · Example: TXT
A
AAAA
CNAME
ALIAS
MX
TXT
SRV
CAA
NS
TLSA
name string · Example: _dmarc.example.com
value string · Example: v=DMARC1; p=none; rua=mailto:dmarc@example.com
ttl integer · Example: 3600
priority integer · nullable · Example: 10

Present only for MX and SRV records. null means the upstream DNS provider omitted priority for a priority-capable record.

weight integer · nullable · Example: 5

Present only for SRV records. null means the upstream DNS provider omitted weight for an SRV record.

port integer · nullable · Example: 5060

Present only for SRV records. null means the upstream DNS provider omitted port for an SRV record.

proxied boolean · Example: false

Present only on A, AAAA, and CNAME records when the CDN proxy state is known. Omitted for record types that cannot be proxied.

proxyReason string · Example: Mail server records cannot be proxied because MX records depend on them.

Present only when this proxy-capable record has a customer-facing reason that prevents changing the proxy state.

actions object

Compact action gates for state that belongs to this DNS record. Present only when a server-side action gate is relevant to the record.

actions.canChangeProxy object required
actions.canChangeProxy.allowed boolean required · Example: true
actions.canChangeProxy.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

actions.canChangeProxy.code string · nullable · Example: pending_order

Machine-readable reason code when an action is blocked.

warnings array<object>

Present on DNS write responses when the request succeeded but the resulting same-name record set deserves review, for example multiple A records, remaining AAAA records, or multiple MX records.

warnings[].code string · enum required · Example: same_name_address_records
same_name_address_records
same_name_ipv6_records
same_name_mx_records
warnings[].severity string · enum required · Example: warning
warning
warnings[].message string required · Example: There are now multiple A records for example.com. This is valid for some setups, but if...
warnings[].records array<object> required

Existing records that triggered the warning. The newly created or updated record is the main response object.

warnings[].records[].id string required · Example: drr_01hxa3b4c5d6e7f8g9h0j1k2m4
warnings[].records[].type string required · Example: A
warnings[].records[].name string required · Example: example.com
warnings[].records[].value string required · Example: 198.51.100.25
warnings[].records[].priority integer · nullable · Example: 10

Nullable: may be null when not applicable.

400 Invalid request. The response body is an RFC 7807 Problem Details document.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Not found. The resource does not exist or is not owned by the caller.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
409 Conflict. See the Problem Details code for the route-specific blocker and recovery fields.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
POST https://cloud.hostup.se/api/v2/dns-zones/{id}/records
For AI assistants
View as Markdown
cURL 
curl -X POST "https://cloud.hostup.se/api/v2/dns-zones/zone_01hxa3b4c5d6e7f8g9h0j1k2m3/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600
  }'
Response 
{
  "id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "type": "TXT",
  "name": "_dmarc.example.com",
  "value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
  "ttl": 3600
}
Request Body A 
{
  "type": "A",
  "name": "@",
  "value": "192.0.2.1",
  "ttl": 3600
}