DNS API documentation
Note
The DNS API V1 described here is deprecated, refer to the OpenAPI documentation for DNS API V2.
The key feature of Exoscale DNS resides in its simple JSON API, which allows you to program hosted zones and records.
API authentication
There are two levels of authentication:
- A global authentication which allows listing registered zones
- A per-zone authentication realm
The API endpoint lives at https://api.exoscale.com/dns and authentication
is done through the X-DNS-Token
header for the global realm, or
X-DNS-Domain-Token
header for the per-zone realm.
The X-DNS-Token
header follows this layout: API_KEY:API_SECRET
.
This layout is your standard Exoscale API Key and secret, separated with a colon.
The X-DNS-Domain-Token
follows a simpler layout: ZONE_TOKEN
.
Instead of a fixed token, you will supply the per-zone token
retrieved via the GET /domains
call.
JSON API
Domain API
GET /domains
List all domains
Example query:
curl -H 'X-DNS-Token: <api-key:secret>' \
-H 'Accept: application/json' \
https://api.exoscale.com/dns/v1/domains
Example response:
[
{
"domain": {
"id": 228,
"user_id": 19,
"registrant_id": null,
"name": "example.it",
"unicode_name": "example.it",
"token": "domain-token",
"state": "hosted",
"language": null,
"lockable": true,
"auto_renew": false,
"whois_protected": false,
"record_count": 5,
"service_count": 0,
"expires_on": null,
"created_at": "2014-01-15T22:03:49Z",
"updated_at": "2014-01-15T22:03:49Z"
}
},
{
"domain": {
"id": 227,
"user_id": 19,
"registrant_id": 28,
"name": "example.com",
"unicode_name": "example.com",
"token": "domain-token",
"state": "registered",
"language": null,
"lockable": true,
"auto_renew": true,
"whois_protected": false,
"record_count": 7,
"service_count": 0,
"expires_on": "2015-01-16",
"created_at": "2014-01-15T22:01:55Z",
"updated_at": "2014-01-16T22:56:22Z"
}
}
]
POST /domains
Create a domain. Expected input parameters:
domain.name
: zone to host
Example query:
curl -H 'X-DNS-Token: <api-key:secret>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"domain":{"name":"example.com"}}' \
-X POST \
https://api.exoscale.com/dns/v1/domains
Example response:
{
"domain": {
"id": 227,
"user_id": 19,
"registrant_id": 28,
"name": "example.com",
"unicode_name": "example.com",
"token": "domain-token",
"state": "registered",
"language": null,
"lockable": true,
"auto_renew": true,
"whois_protected": false,
"record_count": 7,
"service_count": 0,
"expires_on": "2015-01-16",
"created_at": "2014-01-15T22:01:55Z",
"updated_at": "2014-01-16T22:56:22Z"
}
}
GET /domains/:domain
Retrieve a domain’s details.
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
https://api.exoscale.com/dns/v1/domains/example.com
Example response:
{
"domain": {
"id": 227,
"user_id": 19,
"registrant_id": 28,
"name": "example.com",
"unicode_name": "example.com",
"token": "domain-token",
"state": "registered",
"language": null,
"lockable": true,
"auto_renew": true,
"whois_protected": false,
"record_count": 7,
"service_count": 0,
"expires_on": "2015-01-16",
"created_at": "2014-01-15T22:01:55Z",
"updated_at": "2014-01-16T22:56:22Z"
}
}
DELETE /domains/:domain
Delete a domain.
Example query:
curl -H 'X-DNS-Token: <api-key:secret>' \
-H 'Accept: application/json' \
-X DELETE \
https://api.exoscale.com/dns/v1/domains/example.com
POST /domains/:domain/token
Resets a domain’s token.
curl -H 'X-DNS-Token: <api-key:secret>' \
-H 'Accept: application/json' \
-X POST \
https://api.exoscale.com/dns/v1/domains/example.com/token
Example response:
{
"domain": {
"id": 227,
"user_id": 19,
"registrant_id": 28,
"name": "example.com",
"unicode_name": "example.com",
"token": "domain-token",
"state": "registered",
"language": null,
"lockable": true,
"auto_renew": true,
"whois_protected": false,
"record_count": 7,
"service_count": 0,
"expires_on": "2015-01-16",
"created_at": "2014-01-15T22:01:55Z",
"updated_at": "2014-01-16T22:56:22Z"
}
}
GET /domains/:domain/records
List records for a domain.
Accepts the following parameters:
domain
: Domain name or id
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
https://api.exoscale.com/dns/v1/domains/example.com/records
Example response:
[
{
"record": {
"name": "",
"ttl": 3600,
"created_at": "2010-07-04T04:41:31Z",
"updated_at": "2010-10-21T15:47:47Z",
"domain_id": 1,
"id": 31,
"content": "1.2.3.4",
"record_type": "A",
"prio": null
}
}
]
POST /domains/:domain/records
Create a new record. Accepts the following parameters:
domain
: Domain name or id
The JSON input accepts the following parameters:
record.name
: record name, *requiredrecord.record_type
: record type (A, CNAME, MX, …), requiredrecord.content
: record content requiredrecord.ttl
: optional record TTLrecord.prio
: record priority when applicable
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-X POST \
-d '<json>' \
https://api.exoscale.com/dns/v1/domains/example.com/records
{
"record": {
"name": "",
"record_type": "MX",
"content": "mail.example.com",
"ttl": 3600,
"prio": 10
}
}
Example response:
{
"record": {
"name": "",
"ttl": 3600,
"created_at": "2010-07-04T04:41:31Z",
"updated_at": "2010-10-21T15:47:47Z",
"domain_id": 1,
"id": 31,
"content": "mail.example.com",
"record_type": "MX",
"prio": 10
}
}
GET /domains/:domain/records/:id
Retrieve record details. Accepts the following parameters:
domain
: Domain name or IDid
: Record ID
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
https://api.exoscale.com/dns/v1/domains/example.com/records/1
Example response:
{
"record": {
"name": "",
"ttl": 3600,
"created_at": "2010-07-04T04:41:31Z",
"updated_at": "2010-10-21T15:47:47Z",
"domain_id": 1,
"id": 31,
"content": "1.2.3.4",
"record_type": "A",
"prio": null
}
}
PUT /domains/:domain/records/:id
Modify a record’s content. Accepts the following parameters:
record.name
: record namerecord.content
: record contentrecord.ttl
: optional record TTLrecord.prio
: record priority when applicable
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-X PUT \
-d '<json>' \
https://api.exoscale.com/dns/v1/domains/example.com/records/1
Example response:
{
"record": {
"name": "",
"ttl": 3600,
"created_at": "2010-07-04T04:41:31Z",
"updated_at": "2010-10-21T15:47:47Z",
"domain_id": 1,
"id": 31,
"content": "1.2.3.4",
"record_type": "A",
"prio": null
}
}
DELETE /domains/:domain/records/:id
Delete a record.
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
-X DELETE \
https://api.exoscale.com/dns/v1/domains/example.com/records/1
GET /domains/:domain/zone
Get the domain as a zone file content. (This API endpoint responds also to the MIME type plain/text).
Example query:
curl -H 'X-DNS-Domain-Token: <token>' \
-H 'Accept: application/json' \
https://api.exoscale.com/dns/v1/domains/example.com/zone