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 (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)