Skip to main content

Managing DNS records over the API

Setting a A/AAAA record for a domain or subdomain​

To modify the A or AAAA records of an existing domain or subdomain, you first need to obtain its DNS zone id. For this, list the project's DNS zones by using the GET/v2/projects/{projectId}/dns-zones/ endpoint. In the following examples, this zone ID will be referred to as ZONE_ID.

You can then modify your A and AAAA records using the PUT/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/ operation. Note that this operation is used for modifying both A and AAAA records (even though the recordSet path parameter should always be set to "a"):

PUT /v2/dns-zones/ZONE_ID/record-sets/a HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "a": [
    "203.0.113.1",
    "203.0.113.2"
  ],
  "aaaa": [
    "2001:0DB8::1",
    "2001:0DB8::2"
  ],
  "settings": {
    "ttl": {
      "auto": true
    }
  }
}
See full request reference at: PUT/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/

Setting a CNAME record for a subdomain​

Optional: Creating a subdomain first​

If the subdomain does not already exist, you need to create it first:

POST /v2/ingresses HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "hostname": "subdomain.domain.example",
  "paths": [
    {
      "path": "/",
      "target": {
        "useDefaultPage": true
      }
    }
  ],
  "projectId": "PROJECT_ID"
}
See full request reference at: POST/v2/ingresses/

In this case, the paths property is largely irrelevant (since you'll be setting a custom CNAME record anyway), but it still is required by the API. Use the useDefaultPage target from the example if you do not want to explicitly define a domain target.

Setting the CNAME record​

When the subdomain exists, you first need to obtain its DNS zone id. For this, list the project's DNS zones by using the GET/v2/projects/{projectId}/dns-zones/ endpoint.

Given the zone ID (referenced as ZONE_ID in subsequent examples), you can then set or modify the CNAME record:

PUT /v2/dns-zones/ZONE_ID/record-sets/cname HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "fqdn": "your-cname-target.example",
  "settings": {
    "ttl": {
      "auto": true
    }
  }
}
See full request reference at: PUT/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/

Resetting custom A/AAAA/MX records​

Typically, A, AAAA and MX records are managed by the mittwald platform, which you can override by setting custom records using the methods explained above. If you want to reset a record set to being managed by the mittwald platform, use the POST/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/actions/set-managed/ operation.

POST /v2/dns-zones/ZONE_ID/record-sets/a/actions/set-managed HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{}
See full request reference at: POST/v2/dns-zones/{dnsZoneId}/record-sets/{recordSet}/actions/set-managed/