API

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 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",
}

Example of setting up a domain

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns \
  -d name=example.com
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/dns', 'name=example.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",
    "name": "example.com">
  }
]

Example of listing domain names

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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.

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 202 Accepted.

{
  "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
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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 the choice of RR type from a, cname, mx or txt
name 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 the IP address (A or MX), hostname (CNAME or MX) or text value (TXT) to serve for this record
priority useful for MX records only, the priority mail should be attempted it (defaults to 10)
ttl how long caching DNS servers should cache this record for, in seconds (the minimum is 600 and the default if unspecified is 3600)

Response

The response is a JSON object that confirms the details given..

{
  "id": "76cc107f-fbef-4e2b-b97f-f5d34f4075d3",
  "domain_id": "edc5dacf-a2ad-4757-41ee-c12f06259c70",
  "name": "mail",
  "value": "10.0.0.1",
  "type": "mx",
  "priority": 10,
  "ttl": 3600
}

Example of creating a DNS record

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns/12345/records \
  -d name=mail&value=10.0.0.1&type=mx
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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)

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",
    "name": "mail",
    "value": "10.0.0.1",
    "type": "mx",
    "priority": 10,
    "ttl": 3600
  }
]

Example of listing DNS records

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/dns/12345/records
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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 202 Accepted.

{
  "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
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/dns/12345/records/12345678-9012-3456-7890-123456789012', headers)