DNS
We host reverse DNS for all instances automatically. If you'd like to manage forward (normal) DNS for your domains, you can do that for free within your account.
This API is effectively split in to two parts: 1) Managing domain names themselves, and 2) Managing records within those domain names.
We don't offer registration of domains names, this is purely for hosting the DNS. If you're looking to buy a domain name, we recommend LCN.com for their excellent friendly support and very competitive prices.
Setup a new domain
Any user can add a domain name (that has been registered elsewhere) to be managed by Civo.com. You should adjust the nameservers of your domain (through your registrar) to point to ns0.civo.com
and ns1.civo.com
.
New domains are setup by sending a POST
request to https://api.civo.com/v2/dns
.
Request
There are no URL parameters and only one POST parameter
Name | Description |
---|---|
name | (required) the domain name, e.g. "example.com" |
Response
The response is a JSON object that confirms the details given, with an id
ready for you to add records to the domain.
{
"result": "success",
"id": "927ecdb9-90a3-4f3c-8280-1a1924da926a",
"name": "example.com"
}
Example of setting up a domain
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns \
-d name=example.com
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.post(
'https://api.civo.com/v2/dns',
{name: "example.com"},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.post('/v2/dns', 'name=example.com', headers)
Update a domain
After creating a custom domain, any user can update their domain.
Domains are updated by sending a PUT
request to https://api.civo.com/v2/dns/:id
.
Request
The following parameter(s) should be sent along with the request:
Name | Description |
---|---|
name | (required) the domain name, e.g. "example.com" |
Response
The response is a JSON object that simply confirms that the domain was updated.
{
"result": "success",
"id": "927ecdb9-90a3-4f3c-8280-1a1924da926a",
"name": "myexample.com"
}
Example of updating a domain
curl -H "Authorization: bearer 12345" -X PUT https://api.civo.com/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a \
-d name=myexample.com
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.put(
'https://api.civo.com/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a',
{
"name": "myexample.com"
},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.put('/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a', 'name=myexample.com', headers)
List domain names
A list of all domain names within your account are available by sending a GET
request to https://api.civo.com/v2/dns
.
Request
This request takes no parameters.
Response
The response is a JSON array of objects that lists each domain name.
[
{
"id": "7088fcea-7658-43e6-97fa-273f901978fd",
"account_id": "e7e8386e-434e-482f-95e0-c406e5d564c2",
"name": "example.com",
}
]
Example of listing domain names
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.get(
'https://api.civo.com/v2/dns',
{},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.get('/v2/dns', headers)
Deleting a domain
An account holder can remove a domain, which will automically remove all DNS records. Domains are updated by sending a DELETE
request to https://api.civo.com/v2/dns/:id
.
Request
This request takes no parameters except the ID of the domain to delete is in the URL. No confirmation step is required, this step will remove the domain and all records immediately.
Response
The response from the server will be a JSON block. The response will include a result
field and the HTTP status will be 200 OK
.
{
"result": "success"
}
Example of deleting a DNS domain
curl -H "Authorization: bearer 12345" \
-X DELETE https://api.civo.com/v2/dns/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.del(
'https://api.civo.com/v2/dns/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa',
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.delete('/v2/dns/dc9ffcf8-c2ff-4c38-b297-30f790cf56fa', headers)
Create a new DNS record
An account holder can create DNS records for a specific domain.
New DNS records are created by sending a POST
request to https://api.civo.com/v2/dns/:domain_id/records
.
Request
The following parameter are required for setting DNS records:
Name | Description |
---|---|
type | (required) the choice of RR type from a , cname , mx or txt |
name | (required) the portion before the domain name (e.g. www ) or an @ for the apex/root domain (you cannot use an A record with an amex/root domain) |
value | (required) the IP address (A or MX), hostname (CNAME or MX) or text value (TXT) to serve for this record |
priority | (optional) useful for MX records only, the priority mail should be attempted it (defaults to 10) |
ttl | (optional) how long caching DNS servers should cache this record for, in seconds (the minimum is 600 and the default if unspecified is 600) |
Response
The response is a JSON object that confirms the details given..
{
"id": "76cc107f-fbef-4e2b-b97f-f5d34f4075d3",
"created_at": "2019-04-11T12:47:56.000+01:00",
"updated_at": "2019-04-11T12:47:56.000+01:00",
"account_id": null,
"domain_id": "edc5dacf-a2ad-4757-41ee-c12f06259c70",
"name": "mail",
"value": "10.0.0.1",
"type": "mx",
"priority": 10,
"ttl": 600
}
Example of creating a DNS record
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns/12345/records \
-d name=mail -d value=10.0.0.1 -d type=mx
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.post(
'https://api.civo.com/v2/dns/12345/records',
{
name: "mail",
value: "10.0.0.1",
type: "mx"
},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.post('/v2/dns/12345/records', 'name=mail&value=10.0.0.1&type=mx', headers)
Update a DNS record
After creating a DNS record, any user can update their DNS record.
DNS records are updated by sending a PUT
request to https://api.civo.com/v2/dns/:domain_id/records/:id
.
Request
The following parameter(s) should be sent along with the request:
Name | Description |
---|---|
type | (optional) the choice of RR type from a , cname , mx or txt |
name | (optional) the portion before the domain name (e.g. www ) or an @ for the apex/root domain (you cannot use an A record with an amex/root domain) |
value | (optional) the IP address (A or MX), hostname (CNAME or MX) or text value (TXT) to serve for this record |
priority | (optional) useful for MX records only, the priority mail should be attempted it (defaults to 10) |
ttl | (optional) how long caching DNS servers should cache this record for, in seconds (the minimum is 600 and the default if unspecified is 600) |
Response
The response is a JSON object that simply confirms that the DNS record was updated.
{
"id": "76cc107f-fbef-4e2b-b97f-f5d34f4075d3",
"created_at": "2019-04-11T12:47:56.000+01:00",
"updated_at": "2019-04-11T12:47:56.000+01:00",
"account_id": null,
"domain_id": "edc5dacf-a2ad-4757-41ee-c12f06259c70",
"name": "email",
"value": "10.0.0.1",
"type": "mx",
"priority": 10,
"ttl": 600
}
Example of updating a DNS record
curl -H "Authorization: bearer 12345" \
-X PUT https://api.civo.com/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a/records/76cc107f-fbef-4e2b-b97f-f5d34f4075d3 \
-d name=email
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.put(
'https://api.civo.com/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a/records/76cc107f-fbef-4e2b-b97f-f5d34f4075d3',
{
"name": "email"
},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.put('/v2/dns/927ecdb9-90a3-4f3c-8280-1a1924da926a/records/76cc107f-fbef-4e2b-b97f-f5d34f4075d3', 'name=email', headers)
List DNS records
A list of all DNS records in the specified domain is available by sending a GET
request to https://api.civo.com/v2/dns/:id/records
.
Request
This request takes no parameters.
Response
The response is a JSON array of objects that describes summary details for each instance.
[
{
"id": "76cc107f-fbef-4e2b-b97f-f5d34f4075d3",
"created_at": "2019-04-11T12:47:56.000+01:00",
"updated_at": "2019-04-11T12:47:56.000+01:00",
"account_id": null,
"domain_id": "edc5dacf-a2ad-4757-41ee-c12f06259c70",
"name": "mail",
"value": "10.0.0.1",
"type": "mx",
"priority": 10,
"ttl": 600
}
]
Example of listing DNS records
curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns/12345/records
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.get(
'https://api.civo.com/v2/dns/12345/records',
{},
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.get('/v2/dns/12345/records', headers)
Deleting a DNS record
An account holder can remove a DNS record from a domain by sending a DELETE
request to https://api.civo.com/v2/dns/:domain_id/records/:id
.
Request
This request takes no parameters, the ID of the DNS record to delete and the ID of the domain are in the URL. No confirmation step is required, this step will remove the DNS record immediately.
Response
The response from the server will be a JSON block. The response will include a result
field and the HTTP status will be 200 OK
.
{
"result": "success"
}
Example of deleting a DNS record
curl -H "Authorization: bearer 12345" \
-X DELETE https://api.civo.com/v2/dns/12345/records/12345678-9012-3456-7890-123456789012
// At a shell prompt run:
// npm init -y
// npm i --save request
var request = require('request');
request.del(
'https://api.civo.com/v2/dns/12345/records/12345678-9012-3456-7890-123456789012',
function (error, response, body) {
if (!error && response.statusCode == 200) {
console.log(body)
}
}
).auth(null, null, true, '12345');
require 'net/http'
http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true
headers = {
'Authorization' => 'bearer 12345',
'Content-Type' => 'application/x-www-form-urlencoded'
}
resp, data = http.delete('/v2/dns/12345/records/12345678-9012-3456-7890-123456789012', headers)