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. 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. Use ALIAS, not CNAME, when the zone root should point at another hostname. TXT and SPF values 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. 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

PUT /api/v2/dns-zones/{id}/records/{recordId} Update DNS record DELETE /api/v2/dns-zones/{id}/records/{recordId} Delete DNS record GET /api/v2/dns-zones/{id} Get DNS zone and records

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

SPF

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:[email protected]

Record target or content. Send TXT/SPF 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 DKIM/SPF/DMARC 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

SPF

SRV

CAA

NS

TLSA

name string · Example: _dmarc.example.com

value string · Example: v=DMARC1; p=none; rua=mailto:[email protected]

ttl integer · Example: 3600

priority integernull · Example: null

weight integernull · Example: null

port integernull · Example: null

status string · enum · Example: active

active

disabled

pending

error

unknown

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:[email protected]",
  "ttl": 3600,
  "priority": null,
  "weight": null,
  "port": null,
  "status": "pending"
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "A",
        "AAAA",
        "CNAME",
        "ALIAS",
        "MX",
        "TXT",
        "SPF",
        "SRV",
        "CAA",
        "NS",
        "TLSA"
      ]
    },
    "name": {
      "type": "string"
    },
    "value": {
      "type": "string"
    },
    "ttl": {
      "type": "integer"
    },
    "priority": {
      "type": [
        "integer",
        "null"
      ]
    },
    "weight": {
      "type": [
        "integer",
        "null"
      ]
    },
    "port": {
      "type": [
        "integer",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled",
        "pending",
        "error",
        "unknown"
      ]
    }
  }
}

Request Body A

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