Changes to the DNS API

We recently made some changes to our DNS API. This page outlines some of the key changes which you may find useful if you have previously developed something using the previous DNS API.

This documentation will hopefully help with a migration. If you have any other questions, please do feel free to jump to Slack and we'll be happy to help.

New documentation

Full documentation for the new APIs is available here.


The old API will continue to work as normal for now. We plan to fully remove the old DNS endpoints on 30th November 2021.

API documentation for the old endpoints has already been replaced.

Changes to paths

Previously all DNS endpoints were available at paths similar to /core/v1/dns/zones/... or /core/v1/organizations/:org/dns/zones. This has now changed and all API endpoints have new paths. There is no overlap so you will need to update all paths in your implementation.

Changes to TTL for zones

When setting the TTL for zones, it should now be provided as default_ttl rather than just ttl.

Removal of dedicated update TTL endpoint

The update_ttl endpoint for a zone has been removed and replaced with an update zone endpoint.

Argument changed when creating and updating records

When passing the properties required for a DNS record it was previously called details but has now been renamed to properties.

Passing content arguments for records

This is the most significant change that may require the most engineering to update. Each DNS record has a different set of arguments depending on what type of DNS record you have. When you create or update DNS records you will need to ensure that you pass the arguments required for the specific type you request.

Previously, you simply sent all arguments for the record in attribute called properties. With this API, you will need to provide them differently. It is required that you provide an object containing a single key where the key matches the type of the record. For example:

  "properties": {
    "name": "example",
    "type": "CNAME",
    "properties": {
      "CNAME": {
        "hostname": ""

Full details about the arguments available for each DNS record type can be found in the documentation.

It's very important to note that you can't simply provide the attributes for the record directly under the properties argument. They must be within another hash where the key is matches the value in the type argument. The reason for this is that the whole API is now strictly typed which allows for the improved self-documentation and the ability to use the API more easily in typed languaged like Go.

Other changes

There may be other minor changes to the arugment names and verification. We recommend that you read the new documentation and base any implementation on that.