Create DNS record

Read full description Hide full description

Create a 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. 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

Use Authorization: Bearer <token> for API keys. Dashboard sessions may also use hostup_session.

Context

Related endpoints

GET /api/v2/dns-zones/{id}/records List DNS zone records PUT /api/v2/dns-zones/{id}/records/{recordId} Update DNS record PATCH /api/v2/dns-zones/{id}/records/{recordId} Update DNS record proxying

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

Accept Example

Content-Type Example

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 · Example: 3600

priority integer · Example: 10

weight integer · Example: 0

port integer · 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 integernull · Example: 10

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

weight integernull · Example: 5

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

port integernull · 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 stringnull required · Example: null

actions.canChangeProxy.code stringnull · 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 integernull · Example: 10

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

Scenario

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
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "A",
        "AAAA",
        "CNAME",
        "ALIAS",
        "MX",
        "TXT",
        "SRV",
        "CAA",
        "NS",
        "TLSA"
      ]
    },
    "name": {
      "type": "string"
    },
    "value": {
      "type": "string"
    },
    "ttl": {
      "type": "integer"
    },
    "priority": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Present only for MX and SRV records. `null` means the upstream DNS provider omitted priority for a priority-capable record."
    },
    "weight": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Present only for SRV records. `null` means the upstream DNS provider omitted weight for an SRV record."
    },
    "port": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Present only for SRV records. `null` means the upstream DNS provider omitted port for an SRV record."
    },
    "proxied": {
      "type": "boolean",
      "description": "Present only on A, AAAA, and CNAME records when the CDN proxy state is known. Omitted for record types that cannot be proxied."
    },
    "proxyReason": {
      "type": "string",
      "description": "Present only when this proxy-capable record has a customer-facing reason that prevents changing the proxy state."
    },
    "actions": {
      "type": "object",
      "description": "Compact action gates for state that belongs to this DNS record. Present only when a server-side action gate is relevant to the record.",
      "properties": {
        "canChangeProxy": {
          "type": "object",
          "properties": {
            "allowed": {
              "type": "boolean"
            },
            "reason": {
              "type": [
                "string",
                "null"
              ]
            },
            "code": {
              "type": [
                "string",
                "null"
              ],
              "description": "Machine-readable reason code when an action is blocked."
            }
          }
        }
      }
    },
    "warnings": {
      "type": "array",
      "description": "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.",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "same_name_address_records",
              "same_name_ipv6_records",
              "same_name_mx_records"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "warning"
            ]
          },
          "message": {
            "type": "string"
          },
          "records": {
            "type": "array",
            "description": "Existing records that triggered the warning. The newly created or updated record is the main response object.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "priority": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Request Body A

{
  "type": "A",
  "name": "@",
  "value": "192.0.2.1",
  "ttl": 3600
}