Add DNS Record

Adds a new DNS record to a domain managed by your organization.

POST /api/v1/machine/domain-manager/dns-records

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`domain`	string	Yes	The domain name to add the record to (e.g., "example.com")
`record`	object	Yes	The DNS record to add
`record.type`	string	Yes	Record type (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
`record.name`	string	Yes	Host name ("@" for root, or subdomain like "www")
`record.value`	string	Yes	Record value (IP address, hostname, or text)
`record.ttl`	number	No	Time to live in seconds (default: 300)
`record.mxPref`	number	No	MX priority (only for MX records, lower = higher priority)

Example Request Body

{
  "domain": "example.com",
  "record": {
    "type": "A",
    "name": "www",
    "value": "192.168.1.1",
    "ttl": 300
  }
}

Response

Success (200 OK)

Returns all DNS records for the domain, including the newly added record.

{
  "domain": "example.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "CNAME",
      "name": "mail",
      "value": "example.com.",
      "ttl": 300
    }
  ]
}

Response Fields

Field	Type	Description
`domain`	string	The domain name
`records`	array	Array of all DNS records for the domain
`records[].type`	string	Record type (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
`records[].name`	string	Host name ("@" for root, or subdomain like "www")
`records[].value`	string	Record value (IP, hostname, or text)
`records[].ttl`	number	Time to live in seconds
`records[].mxPref`	number	MX priority (only for MX records)

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

403 Forbidden - Domain not managed through R4

{
  "error": {
    "code": "domain_not_managed",
    "message": "The domain \"example.com\" is not managed through R4. DNS records can only be modified for domains purchased through the R4 platform."
  }
}

404 Not Found - Domain not found in your organization

{
  "error": {
    "code": "domain_not_found",
    "message": "The domain \"example.com\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/domain-manager/dns-records" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "record": {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    }
  }'

Use Cases

Infrastructure automation: Automatically configure DNS when provisioning servers
CI/CD pipelines: Set up DNS records as part of deployment workflows
Subdomain management: Programmatically create subdomains for new services
Email configuration: Add MX, SPF, and DKIM records for email setup
Domain verification: Add TXT records for third-party service verification

DNS Record Types

A Record

Maps a domain to an IPv4 address.

{ "type": "A", "name": "@", "value": "192.168.1.1", "ttl": 300 }

AAAA Record

Maps a domain to an IPv6 address.

{ "type": "AAAA", "name": "@", "value": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "ttl": 300 }

CNAME Record

Creates an alias from one domain to another.

{ "type": "CNAME", "name": "www", "value": "example.com.", "ttl": 300 }

MX Record

Specifies mail servers for the domain. Lower mxPref values indicate higher priority.

{ "type": "MX", "name": "@", "value": "mail.example.com.", "ttl": 300, "mxPref": 10 }

TXT Record

Contains arbitrary text data, commonly used for SPF, DKIM, and domain verification.

{ "type": "TXT", "name": "@", "value": "v=spf1 include:_spf.google.com ~all", "ttl": 300 }

NS Record

Specifies authoritative nameservers for the domain.

{ "type": "NS", "name": "@", "value": "ns1.example.com.", "ttl": 86400 }

Notes

Only domains purchased through R4 (internalPurchase: true) can have their DNS records modified
External domains (registered elsewhere) cannot be modified through this endpoint
The domain must be associated with a tenant in your organization
DNS changes may take time to propagate (typically 5 minutes to 48 hours depending on TTL)
The response includes all DNS records for the domain, not just the newly added one