DNS APIv2beta1

Download OpenAPI

Introduction

The DNS API allows you to manage your DNS zones and records.

Features

  • Manage your domain with one or more zones
  • Use Dynamic Records to optimize and ease your Infra As Code

A domain name is an identification string that defines a realm of administrative autonomy, authority or control within the Internet. Domain names are formed by the rules and procedures of the Domain Name System (DNS). Any name registered in the DNS is a domain name.

Domains are further divided into sub-domains, each becoming a DNS zone itself with its own set of administrators and DNS servers.

The term domain is used in the business functions of the entity assigned to it and the term zone is usually used for configuration of DNS services.

example.com is the domain and has only one owner who can manage it.

By default, the domain only has a root zone (no sub domain).

example.com zone allows the configuration of records such as:

example.com
├── (root)
├── www # www.example.com
├── mail # mail.example.com
└── www.dev # www.dev.example.com

If we add a DNS zone to the sub domain dev.example.com, we get:

example.com
├── (root)
│ ├── www # www.example.com
│ └── mail # mail.example.com

├── dev
└── www # www.dev.example.com
  • Only the owner of the domain can use the domain services
  • Each zone supports the creation of sub-zones, which inherit the parent's projectID

In the simplest case you will only need the root zone.

But multiple zones (i.e. sub-domains) allow:

  • access delegation to zone(s) (preventing access to the root zone)
  • (future) features based on templates
  • performance tuning (for example if you have 10k records, it will be better to divide them into x zones / sub-domains)

Remark: to be RFC compliant, each zone will automatically have NS records added.

An internationalized domain name (IDN) is an Internet domain name that contains at least one label that is displayed in software applications, which is in whole or in part in a language-specific script or alphabet, such as Arabic, Chinese, Cyrillic, Tamil, Hebrew or the Latin alphabet-based characters with diacritics or ligatures, such as French. These writing systems are encoded by computers in multi-byte Unicode. Internationalized domain names are stored in the Domain Name System as ASCII strings using Punycode transcription.

Example: allélua.com converted in IDN is xn--alllua-dva.com.

To simplify its use, the DNS API uses unicode (UTF-8) for name and data fields.

Login to your Scaleway account and create a token from the credentials page. A secret_key and an access_key will be displayed on your screen, the secret_key will be used as X-Auth-Token.

Reference: https://www.scaleway.com/docs/generate-an-api-token/

The organization id is required to get the permissions. You will need to query:

curl https://account.scaleway.com/organizations -H "X-Auth-Token: $secret_key"

To get your organization id:

{
"organizations":[
{
"id":"000a115d-2852-4b0a-9ce8-47f1134ba95a", <-----
"name":"jsnow@got.wint",
"users": [{}]
}
]
}

Reference: https://www.scaleway.com/docs/retrieve-my-organization-id-throught-the-api/

Get the service info

curl -s --request GET \
--url https://api.scaleway.com/domain/v2beta1

{
"name": "Scaleway Name Service",
"description": "Domain and DNS services",
"version": "v2beta1",
"documentation_url": "https://developers.scaleway.com/en/products/domain/api/"
}

To use Scaleway DNS to manage your Domain, you need to register your Domain with:

curl --request POST \
--url http://api.scaleway.com/domain/v2beta1/domains/external-domain \
--header 'content-type: application/json' \
--header 'x-auth-token: xxxxxxx' \
--data '{
"domain": "domain-external.test",
"project_id": "xxxxxx"
}

{
"domain": "domain-external.test",
"organization_id": "xxxxxx",
"project_id": "xxxxxx",
"validation_token": "0bb2c236-7d14-4ab3-8a6d-83d1b460a14b",
"created_at": "2020-05-07T13:24:35Z"
}

You will then have 48h to set up a TXT record to confirm the ownership of the Domain:

  • name: _scaleway-challenge
  • content: the validation token

Upon validation you will receive a confirmation email and the Domain will be available on the API. You will then have to update your DNS nameservers to Scaleway DNS servers: ns0.dom.scw.cloud and ns1.dom.scw.cloud.

  • for a Domain: at your registrar to point your Domain to Scaleway DNS servers
  • for a sub Domain: at your parent DNS server to point your sub Domain to Scaleway DNS servers

Dnssec

If need: remove your DNSSEC settings on your registrar before migrating to our service. You will be able to re-setup if after.

  • record name format is always in "short" format not FQDN.
  • for zone example.com, name test.example.com. will be converted to test
  • for data value, if not in RFC format, it will be corrected if possible:
    • for TXT, quotes will be added
    • for CNAME, if not in FQDN, the zone will be added
    • etc.
curl --request GET \
--url https://api.scaleway.com/domain/v2beta1/domains \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'

{
"total_count": 1,
"domains": [
{
"domain": "scaleway-test5.com",
"organization_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx",
"project_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx",
"auto_renew_status": "feature_status_unknown",
"dnssec_status": "feature_status_unknown",
"epp_code": [],
"expired_at": null,
"updated_at": "1970-01-01T00:00:00Z",
"registrar": "EXTERNAL",
"is_external": true,
"status": "active"
}
]
}
curl --request GET \
--url https://api.scaleway.com/domain/v2beta1/domains/scaleway-test5.com/zones \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'

{
"total_count": 2,
"dns_zones": [
{
"domain": "scaleway-test5.com",
"subdomain": "",
"ns_default": [],
},
{
"domain": "scaleway-test5.com",
"subdomain": "test-zone",
"ns_default": [],
}
]
}
curl --request GET \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/ \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'

{
"total_count": 3,
"dns_zones": [
{
"domain": "scaleway-test5.com",
"subdomain": "",
"ns_default": [],
},
{
"domain": "scaleway-test5.com",
"subdomain": "test-zone",
"ns_default": [],
},
{
"domain": "testscaleway-test5.com",
"subdomain": "test-zone3",
"ns_default": [],
}
]
}
curl --request GET \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/subdomain.scaleway-test5.com/records \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'

{
"total_count": 2,
"records": [
{
"data": "ns0.online.net.",
"name": "",
"priority": 0,
"ttl": 0,
"type": "NS",
"comment": null
},
{
"data": "ns1.online.net.",
"name": "",
"priority": 0,
"ttl": 0,
"type": "NS",
"comment": null
}
}

Remarks:

  • The clear operation clears all the records (thus allows to restart from scratch)
  • The operation works the same as PowerDns patch
  • If the zone does not exist but is included in a managed zone, the API will create the new (sub) zone
curl --request PATCH \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/subdomain.scaleway-test5.com/records \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx' \
--data '{
"changes": [
{
"clear": {}
},
{
"add": {
"records": [
{
"name": "test1",
"data": "127.0.0.1",
"type": "A",
"ttl": 3600
},
{
"name": "test2",
"data": "127.0.0.1",
"type": "A",
"ttl": 3600
}
]
}
},
{
"set": {
"id_fields": {
"type": "A",
"name": "test2"
},
"records": [
{
"name": "test2",
"data": "127.0.0.2",
"type": "A",
"ttl": 3600
}
]
}
},
{
"add": {
"records": [
{
"name": "test3",
"data": "127.0.0.3",
"type": "A",
"ttl": 3600
},
{
"name": "test3",
"data": "127.0.0.4",
"type": "A",
"ttl": 3600
}
]
}
},
{
"delete": {
"id_fields": {
"name": "test3",
"data": "127.0.0.4",
"type": "A",
"ttl": 3600
}
}
}
]
}'


{
"records": [
{
"id": "<UUID>",
"data": "127.0.0.1",
"name": "test1",
"priority": 0,
"ttl": 3600,
"type": "A"
},
{
"id": "<UUID>",
"data": "127.0.0.1",
"name": "test2",
"priority": 0,
"ttl": 3600,
"type": "A"
},
{
"id": "<UUID>",
"data": "127.0.0.2",
"name": "test2",
"priority": 0,
"ttl": 3600,
"type": "A"
},
{
"id": "<UUID>",
"data": "127.0.0.3",
"name": "test3",
"priority": 0,
"ttl": 3600,
"type": "A"
}
]
}

For external domain:

You have not DNSSEC set at your registrar

curl --request POST \
--url
https://api.scaleway.com/domain/v2alpha2/domains/example.com/enable-dnssec
\
--header 'content-type: application/json' \
--header 'x-auth-token: xxxxxxxxxxxxxxxxx' \
--data '{
}
}'

You will have to set in your registrar the DS returned in the result:

{
"domain":{
"domain":"example.fr",
"auto_renew_status":"enabled",
"dnssec_status":"disabled",
"ds_records":[
{
"key_id":49071,
"algorithm":"ecdsap256sha256",
"digest":{
"type":"sha_384",
"digest":"c14421f739e35b62e3383d5972263f93610dea31da48a1990453752cf1b4f4f0314f75ecd0bc9061c51ee41ec7692204"
}
}
],
"epp":[
"clientTransferProhibited"
],
"expired_at":"2021-04-04T12:46:29Z",
"updated_at":"2020-07-07T13:24:27Z",
"registrar":"EXTERNAL",
"is_external":true,
"status":"active",
"......"
}

You have DNSSEC already set at your registrar

Call the API with the right settings:

curl --request POST \
--url
https://api.scaleway.com/domain/v2alpha2/domains/example.com/enable-dnssec
\
--header 'content-type: application/json' \
--header 'x-auth-token: xxxxxxxxxxxxxxxxx' \
--data '{
"ds_record": {
"algorithm": "RSAMD5",
"digest":

{ "type": "SHA_1", "digest": "ABCD" }

}
}'

We provide the classic record types (A, AAAA, CNAME...) along with some dynamic records. At the moment the following dynamic records are supported: http(s) health checks and views.

Service up

This will test if a (http/https) service is up on a provided list of IPs.

An IP is considered healthy if the query response contains the text specified in must_contain.

The Record Type can be one of:

  • A
  • AAAA
curl --request PATCH \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/dom.example.com/records \
--header 'content-type: application/json' \
--header 'x-auth-token: xxxx' \
--data '{
"return_all_records": false,
"changes": [
{
"add": {
"records": [
{
"name": "service-www",
"data": "10.51.2.8",
"type": "A",
"ttl": 600,
"http_service_config": {
"ips": [
"10.51.2.8",
"10.51.3.7",
"10.51.2.9"
],
"must_contain": "I am fine",
"url": "https://www.domain-test.test"
}
}
]
}
}
]
}'

View

View will give responses depending on the requester (or resolver) IP.

Record Type can be:

  • A
  • AAAA
  • CNAME
  • TXT
curl --request PATCH \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/dom.example.com/records \
--header 'content-type: application/json' \
--header 'x-auth-token: xxxxx' \
--data '{
"return_all_records": false,
"changes": [
{
"set": {
"id_fields": {
"name": "test",
"type": "CNAME"
},
"records": [
{
"name": "test",
"data": "default-domain.com.",
"type": "CNAME",
"ttl": 600,
"view_config": {
"views": [
{
"subnet": "10.51.0.0/16",
"data": "filtered-domain.com."
}
]
}
}
]
}
}
]
}'
curl --request GET \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/subdomain.scaleway-test5.com/records \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'


{
"total_count": 3,
"records": [
{
"data": "<UUID>",
"data": "127.0.0.1",
"name": "test1",
"priority": 0,
"ttl": 3600,
"type": "A"
},
{
"data": "<UUID>",
"data": "127.0.0.2",
"name": "test2",
"priority": 0,
"ttl": 3600,
"type": "A"
},
{
"data": "<UUID>",
"data": "127.0.0.3",
"name": "test3",
"priority": 0,
"ttl": 3600,
"type": "A"
}
]
}

Delete the zone AND all the records, NS included:

curl --request DELETE \
--url https://api.scaleway.com/domain/v2beta1/dns-zones/subdomain.scaleway-test5.com/records \
--header 'x-auth-token: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxxx'

{}

List DNS zones

Returns a list of manageable DNS zones. You can filter the DNS zones by domain name.

GET
/domain/v2beta1/dns-zones
Query Parameters

page
number
Page number. The default value is 1.

page_size
number
Page size. The default value is 20.

order_by
string
Possible values are domain_asc, domain_desc, subdomain_asc and subdomain_desc. The default value is domain_asc.

domain
string

dns_zone
string

project_id
nullable string

organization_id
nullable string
200 Response

total_count
number

dns_zones
array
domain
string

subdomain
string

ns
array

ns_default
array

ns_master
array

status
string
Possible values are unknown, active, pending, error and locked. The default value is unknown.

message
nullable string

updated_at
string

project_id
string
Response Example
{
"total_count": 42,
"dns_zones": [
{
"domain": "string",
"subdomain": "string",
"ns": [
"string"
],
"ns_default": [
"string"
],
"ns_master": [
"string"
],
"status": "unknown",
"message": "string",
"updated_at": "string",
"project_id": "string"
}
]
}

Create a new DNS zone.

POST
/domain/v2beta1/dns-zones
Body

domain
string

subdomain
string

project_id
string
Request Example
{
"domain": "string",
"subdomain": "string",
"project_id": "string"
}
200 Response

domain
string

subdomain
string

ns
array

ns_default
array

ns_master
array

status
string
Possible values are unknown, active, pending, error and locked. The default value is unknown.

message
nullable string

updated_at
string

project_id
string
Response Example
{
"domain": "string",
"subdomain": "string",
"ns": [
"string"
],
"ns_default": [
"string"
],
"ns_master": [
"string"
],
"status": "unknown",
"message": "string",
"updated_at": "string",
"project_id": "string"
}

Update the name and/or the organizations for a DNS zone.

PATCH
/domain/v2beta1/dns-zones/{dns_zone}
Path Parameters

dns_zone
required string
Body

new_dns_zone
nullable string

project_id
string
Request Example
{
"new_dns_zone": "string",
"project_id": "string"
}
200 Response

domain
string

subdomain
string

ns
array

ns_default
array

ns_master
array

status
string
Possible values are unknown, active, pending, error and locked. The default value is unknown.

message
nullable string

updated_at
string

project_id
string
Response Example
{
"domain": "string",
"subdomain": "string",
"ns": [
"string"
],
"ns_default": [
"string"
],
"ns_master": [
"string"
],
"status": "unknown",
"message": "string",
"updated_at": "string",
"project_id": "string"
}

Delete a DNS zone and all it's records.

DELETE
/domain/v2beta1/dns-zones/{dns_zone}
Path Parameters

dns_zone
required string
Query Parameters

project_id
string
200 Response

Response Example
{}

Clone an existed DNS zone with all its records into a new one.

POST
/domain/v2beta1/dns-zones/{dns_zone}/clone
Path Parameters

dns_zone
required string
Body

dest_dns_zone
string

overwrite
boolean

project_id
nullable string
Request Example
{
"dest_dns_zone": "string",
"overwrite": "boolean",
"project_id": "string"
}
200 Response

domain
string

subdomain
string

ns
array

ns_default
array

ns_master
array

status
string
Possible values are unknown, active, pending, error and locked. The default value is unknown.

message
nullable string

updated_at
string

project_id
string
Response Example
{
"domain": "string",
"subdomain": "string",
"ns": [
"string"
],
"ns_default": [
"string"
],
"ns_master": [
"string"
],
"status": "unknown",
"message": "string",
"updated_at": "string",
"project_id": "string"
}

Refresh SOA DNS zone. You can recreate the given DNS zone and its sub DNS zone if needed.

POST
/domain/v2beta1/dns-zones/{dns_zone}/refresh
Path Parameters

dns_zone
required string
Body

recreate_dns_zone
boolean

recreate_sub_dns_zone
boolean
Request Example
{
"recreate_dns_zone": "boolean",
"recreate_sub_dns_zone": "boolean"
}
200 Response

dns_zones
array
domain
string

subdomain
string

ns
array

ns_default
array

ns_master
array

status
string
Possible values are unknown, active, pending, error and locked. The default value is unknown.

message
nullable string

updated_at
string

project_id
string
Response Example
{
"dns_zones": [
{
"domain": "string",
"subdomain": "string",
"ns": [
"string"
],
"ns_default": [
"string"
],
"ns_master": [
"string"
],
"status": "unknown",
"message": "string",
"updated_at": "string",
"project_id": "string"
}
]
}

Get the DNS zone TSIG Key to allow AXFR request.

GET
/domain/v2beta1/dns-zones/{dns_zone}/tsig-key
Path Parameters

dns_zone
required string
200 Response

name
string

key
string

algorithm
string
Response Example
{
"name": "string",
"key": "string",
"algorithm": "string"
}
DELETE
/domain/v2beta1/dns-zones/{dns_zone}/tsig-key
Path Parameters

dns_zone
required string
204 Response

Empty response
GET
/domain/v2beta1/ssl-certificates
Query Parameters

page
number
Page number. The default value is 1.

page_size
number
Page size. The default value is 20.

dns_zone
string

project_id
nullable string
200 Response

total_count
number

certificates
array
dns_zone
string

alternative_dns_zones
array

status
string
Possible values are unknown, new, pending, success and error. The default value is unknown.

private_key
string

certificate_chain
string

created_at
string

expired_at
string
Response Example
{
"total_count": 42,
"certificates": [
{
"dns_zone": "string",
"alternative_dns_zones": [
"string"
],
"status": "unknown",
"private_key": "string",
"certificate_chain": "string",
"created_at": "string",
"expired_at": "string"
}
]
}
POST
/domain/v2beta1/ssl-certificates
Body

dns_zone
string

alternative_dns_zones
array
Request Example
{
"dns_zone": "string",
"alternative_dns_zones": [
"string"
]
}
200 Response

dns_zone
string

alternative_dns_zones
array

status
string
Possible values are unknown, new, pending, success and error. The default value is unknown.

private_key
string

certificate_chain
string

created_at
string

expired_at
string
Response Example
{
"dns_zone": "string",
"alternative_dns_zones": [
"string"
],
"status": "unknown",
"private_key": "string",
"certificate_chain": "string",
"created_at": "string",
"expired_at": "string"
}
GET
/domain/v2beta1/ssl-certificates/{dns_zone}
Path Parameters

dns_zone
required string
200 Response

dns_zone
string

alternative_dns_zones
array

status
string
Possible values are unknown, new, pending, success and error. The default value is unknown.

private_key
string

certificate_chain
string

created_at
string

expired_at
string
Response Example
{
"dns_zone": "string",
"alternative_dns_zones": [
"string"
],
"status": "unknown",
"private_key": "string",
"certificate_chain": "string",
"created_at": "string",
"expired_at": "string"
}
DELETE
/domain/v2beta1/ssl-certificates/{dns_zone}
Path Parameters

dns_zone
required string
200 Response

Response Example
{}

Returns a list of Nameservers and their optional glue records for a DNS zone.

GET
/domain/v2beta1/dns-zones/{dns_zone}/nameservers
Path Parameters

dns_zone
required string
Query Parameters

project_id
nullable string
200 Response

ns
array
name
string

ip
array
Response Example
{
"ns": [
{
"name": "string",
"ip": [
"string"
]
}
]
}

Update DNS zone nameservers and set optional glue records.

PUT
/domain/v2beta1/dns-zones/{dns_zone}/nameservers
Path Parameters

dns_zone
required string
Body

ns
array
name
string

ip
array
Request Example
{
"ns": [
{
"name": "string",
"ip": [
"string"
]
}
]
}
200 Response

ns
array
name
string

ip
array
Response Example
{
"ns": [
{
"name": "string",
"ip": [
"string"
]
}
]
}

Returns a list of DNS records of a DNS zone with default NS. You can filter the records by type and name.

GET
/domain/v2beta1/dns-zones/{dns_zone}/records
Path Parameters

dns_zone
required string
Query Parameters

page
number
Page number. The default value is 1.

page_size
number
Page size. The default value is 20.

order_by
string
Possible values are name_asc and name_desc. The default value is name_asc.

name
string

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

project_id
nullable string
200 Response

total_count
number

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string
Response Example
{
"total_count": 42,
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
}

Only available with default NS.
Send a list of actions and records.

Action can be:

  • add:
  • Add new record
  • Can be more specific and add a new IP to an existing A record for example
  • set:
  • Edit a record
  • Can be more specific and edit an IP from an existing A record for example
  • delete:
  • Delete a record
  • Can be more specific and delete an IP from an existing A record for example
  • clear:
  • Delete all records from a DNS zone

All edits will be versioned.

PATCH
/domain/v2beta1/dns-zones/{dns_zone}/records
Path Parameters

dns_zone
required string
Body

changes
array
add
object
Only one of add, set, delete and clear may be set.
records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string

set
object
Only one of add, set, delete and clear may be set.
id
string
(UUID format). Only one of id and id_fields may be set.

id_fields
object
Only one of id and id_fields may be set.
name
string

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

data
nullable string

ttl
nullable number

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string

delete
object
Only one of add, set, delete and clear may be set.
id
string
(UUID format). Only one of id and id_fields may be set.

id_fields
object
Only one of id and id_fields may be set.
name
string

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

data
nullable string

ttl
nullable number

clear
object
Only one of add, set, delete and clear may be set.

return_all_records
nullable boolean
Request Example
{
"changes": [
{
"add": {
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
},
"set": {
"id": "6170692e-7363-616c-6577-61792e636f6d",
"id_fields": {
"name": "string",
"type": "unknown",
"data": "string",
"ttl": 42
},
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
},
"delete": {
"id": "6170692e-7363-616c-6577-61792e636f6d",
"id_fields": {
"name": "string",
"type": "unknown",
"data": "string",
"ttl": 42
}
},
"clear": {}
}
],
"return_all_records": "boolean"
}
200 Response

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string
Response Example
{
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
}

Only available with default NS.
Delete all the records from a DNS zone. All edits will be versioned.

DELETE
/domain/v2beta1/dns-zones/{dns_zone}/records
Path Parameters

dns_zone
required string
200 Response

Response Example
{}

Get a list of DNS zone versions.
The maximum version count is 100.
If the count reaches this limit, the oldest version will be deleted after each new modification.

GET
/domain/v2beta1/dns-zones/{dns_zone}/versions
Path Parameters

dns_zone
required string
200 Response

versions
array
id
string
(UUID format).

created_at
string
Response Example
{
"versions": [
{
"id": "6170692e-7363-616c-6577-61792e636f6d",
"created_at": "string"
}
]
}

Get a list of records from a previous DNS zone version.

GET
/domain/v2beta1/dns-zones/version/{dns_zone_version_id}
Path Parameters

dns_zone_version_id
required string
(UUID format).
200 Response

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string
Response Example
{
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
}

Get all differences from a previous DNS zone version.

GET
/domain/v2beta1/dns-zones/version/{dns_zone_version_id}/diff
Path Parameters

dns_zone_version_id
required string
(UUID format).
200 Response

changes
array
add
object
Only one of add, set, delete and clear may be set.
records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string

set
object
Only one of add, set, delete and clear may be set.
id
string
(UUID format). Only one of id and id_fields may be set.

id_fields
object
Only one of id and id_fields may be set.
name
string

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

data
nullable string

ttl
nullable number

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string

delete
object
Only one of add, set, delete and clear may be set.
id
string
(UUID format). Only one of id and id_fields may be set.

id_fields
object
Only one of id and id_fields may be set.
name
string

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

data
nullable string

ttl
nullable number

clear
object
Only one of add, set, delete and clear may be set.
Response Example
{
"changes": [
{
"add": {
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
},
"set": {
"id": "6170692e-7363-616c-6577-61792e636f6d",
"id_fields": {
"name": "string",
"type": "unknown",
"data": "string",
"ttl": 42
},
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
},
"delete": {
"id": "6170692e-7363-616c-6577-61792e636f6d",
"id_fields": {
"name": "string",
"type": "unknown",
"data": "string",
"ttl": 42
}
},
"clear": {}
}
]
}

Restore and activate a previous DNS zone version.

POST
/domain/v2beta1/dns-zones/version/{dns_zone_version_id}/restore
Path Parameters

dns_zone_version_id
required string
(UUID format).
Body

Request Example
{}
200 Response

Response Example
{}

Import and replace records from a given provider format with default NS.

POST
/domain/v2beta1/dns-zones/{dns_zone}/import-provider
Path Parameters

dns_zone
required string
Body

online_v1
object
Only one of online_v1 may be set.
token
string
Request Example
{
"online_v1": {
"token": "string"
}
}
200 Response

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string
Response Example
{
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
}

Get a DNS zone in a given format with default NS.

GET
/domain/v2beta1/dns-zones/{dns_zone}/raw
Path Parameters

dns_zone
required string
Query Parameters

format
string
Possible values are unknown_raw_format and bind. The default value is unknown_raw_format.
200 Response

name
string

content_type
string

content
string
Response Example
{
"name": "string",
"content_type": "string",
"content": "string"
}

Import and replace records from a given provider format with default NS.

POST
/domain/v2beta1/dns-zones/{dns_zone}/raw
Path Parameters

dns_zone
required string
Body

format
string
Possible values are unknown_raw_format and bind. The default value is unknown_raw_format.

content
string

project_id
string
Request Example
{
"format": "unknown_raw_format",
"content": "string",
"project_id": "string"
}
200 Response

records
array
data
string

name
string

priority
number

ttl
number

type
string
Possible values are unknown, A, AAAA, CNAME, TXT, SRV, TLSA, MX, NS, PTR, CAA and ALIAS. The default value is unknown.

comment
nullable string

geo_ip_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
matches
array
countries
array

continents
array

data
string

default
string

http_service_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
ips
array
(IP address).

must_contain
nullable string

url
string

user_agent
nullable string

strategy
string
Possible values are random and hashed. The default value is random.

weighted_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
weighted_ips
array
ip
string
(IP address).

weight
number

view_config
object
Only one of geo_ip_config, http_service_config, weighted_config and view_config may be set.
views
array
subnet
string

data
string

id
string
Response Example
{
"records": [
{
"data": "string",
"name": "string",
"priority": 42,
"ttl": 42,
"type": "unknown",
"comment": "string",
"geo_ip_config": {
"matches": [
{
"countries": [
"string"
],
"continents": [
"string"
],
"data": "string"
}
],
"default": "string"
},
"http_service_config": {
"ips": "1.2.3.4",
"must_contain": "string",
"url": "string",
"user_agent": "string",
"strategy": "random"
},
"weighted_config": {
"weighted_ips": [
{
"ip": "1.2.3.4",
"weight": 42
}
]
},
"view_config": {
"views": [
{
"subnet": "string",
"data": "string"
}
]
},
"id": "string"
}
]
}