DNS API - DNSExit.com

The DNS API give you the tools to easily update your dynamic IP or manage your domain's DNS Records remotely. You compile your updates at JSON file and post it to our API address. The API is still under development. If you have any suggestions or bugs, please feel free to contact our support. If you need any feature, we would be glad to satisfy your request as much as possible.

DNS API Key

You will need to create a DNS API KEY for your account before you can use DNS API to manage your DNS remotely.

To create an API key, login to your account, click on “Settings” on the left menu and click “DNS API Key” to bring up the API Key creation page. After the API Key has been created, you will need to use the key for every update of your DNS Records.

Dynamic IP Updates Made Easy

Dynamic IP Updates Made Easy
On Windows, Mac, or Linux, schedule a task to execute the following curl command at regular intervals. cURL, which stands for client URL, is a command line tool that developers use to transfer data to and from a server. Curl is typically included in most operating systems. It has been a part of Windows since the release of Windows 10 build 1803 in early May 2018. If the command is not present on your machine, you'll need to install it.
>> curl https://api.dnsexit.com/dns/ud/?apikey=API-Key -d host=hostname1,hostname2
    Note: Simply add the parameter -d ip=xx.xx.xx.xx to override the updated IP(IPv4 or IPv6). Please make sure your update interval is more than 4 minutes.
Using this command, our system will automatically identify your public IP address and update your hosts to the new IP. Alternatively, you can include the parameter -d ip=xx.xx.xx.xx to overwrite the public IP. For multiple hosts, simply separate them with a comma. The API Key can be created at your account Dashboard -> Settings
The return is JSON file with a successfull update like:

{"code" : 0, "message" : "Success - some details about the update"}

code:0 indicates successfull updates while code:1 indicates IP address not changed. Other returning codes indicates errors.

To make your work easier, you may simply click on the following button to start your automatic updates to your IP


To test how it works on browsers, you can simply paste the following URL adress to a web browser:
https://api.dnsexit.com/dns/ud/?apikey=API-Key&host=host.domain.com
Note: You need to replace the API-KEY and hostname with your own api key and hostname

curl (short for "Client URL") is a command line tool that can communicates with a web server with a relevant URL. Or in other words, it is just like a text based web browser. The curl command is built in most Operating Systems including Linux, Unix, MacOS, and Windows (sinc Windows 10 ). If your windows does not have curl command, you can refer to install curl on windows to learn how to install it.

General Guides to Use API

Except quick dynamic IP updates, to use the API, you will need create your updates at a JSON file and post the update file to our API site:

			
>> curl  -H "Content-Type: application/json" --data @/path/jason-file https://api.dnsexit.com/dns/
			

Examples of updating IP addresses

Warning: This method should not be used for dynamic IP updates. For automatic dynamic IP updating, click here.

If you want to update the IP address for your domain example.com to IP 1.1.1.1, you can create a file/tmp/update.json with the following content:


					
   or

					
Note: the domain part can be omitted since the domain will be appended to the name if it does not ends with domain name
  • TTL is in minutes
  • Domain name is Record Type "A" (refer to support type)
  • Content is the IP address fot the domain
  • To post the update, simply post command:

    >> curl  -H "Content-Type: application/json" --data @/tmp/update.json https://api.dnsexit.com/dns/			
    			

    Alternatively, you can skip definition of apikey and domain and specify them at the URL parameter as:


    	
    >> curl  -H "Content-Type: application/json" -H "apikey: Your-API-KEY" -H "domain: example.com" \
    		 --data @/tmp/update.json https://api.dnsexit.com/dns/	
    			
    With the above definition of domain and apikey, you can skip them at the JSON definition as
    
    					
       or
    
    					

    Note: the domain part can be omitted since the domain will be appended to the name if it does not ends with domain name

  • TTL is in minutes
  • Domain name is Record Type "A" (refer to support type)
  • Content is the IP address fot the domain

  • Bear in mind the parameter passed at Headers or http URL parameters will overwrite the value defined at JSON file.

    Server Reply

    Successful reply of the update to the service should return JSON reply file like

    		

    Note: A successful update will always return code: 0; Other codes value indicate there are problems.
    Here are the list of possible server reply codes:

      Reply Code Reply Message Note
      0 Success Actions got executed successfully
      1 Some execution problems May not indicate actions failures. Some action may got executed fine and some may have problems.
      2 API Key Authentication Error The API Key is missing or wrong
      3 Missing Required Definitions Your JSON file may missing some required definitions.
      4 JSON Data Syntax Error Your JSON file has syntax error.
      5 JSON Defined Record Type not Supported Your JSON may try to update some record type not supported by our system
      6 System Error Our system problem. May not be your problem. Contact our support if you got such error.
      7 Error getting post data Our server has problem to receive your JSON posting

    Supported Record Types & Update Commands

    The DNS API supports management for the following DNS Record types and update commands:

    Supported Record type:A, AAAA, TXT, CNAME, SRV, SELF
    Supported Commands:add, delete, update

    Examples - Single Action

    Create DNS for a Domain

    Example JSON File to create DNS for a domain. You put the value "new-dns":"true" to indicate the request is to create new DNS.
    Note: "name":"", "content":"1.1.2.2" will assign the domain to have IP 1.1.2.2. Alternatively, you have put "name":"example.com" instead.

    {
       "new-dns":"true",
       "domain":"example.com",
       "add":{
          "type":"A",
          "name":"",			// same as example.com. assign the domain's IP to be 1.1.2.2
          "content":"1.1.2.2",		// IP of the host
          "ttl":480
       }
    }
    

    Add a New Record

    1. Add SPF for Domain

    Example JSON File to add SPF for the domain. SPF is the TXT record for the domain.

    {
       "domain":"example.com",
       "add":{
          "type":"TXT",
          "name":"",		//same as "name": "example.com"
          "content":"v=spf1 mx include:dnsexit.com ~all",
          "ttl":480,		//ttl value is in minutes 480 = 6 hours
          "overwrite":true		//* optional, default false unless defined. True will overwrite existing settings
       }
    }
    

    2. Add A Record IPV4 (host/subdomain)

    Example JSON File to add A Record. A Record is hostname or subdomain.

    {
       "domain":"example.com",
       "add":{
          "type":"A",
          "name":"host1",		//same as host1.example.com
          "content":"1.1.2.2",	//IP of the host
          "ttl":480
       }
    }
    

    3. Add A Record IPV6 (host/subdomain)

    Example JSON File to add AAAA Record. AAAA Record is hostname or subdomain with IPv6 address.

    {
       "domain":"example.com",
       "add":{
          "type":"AAAA",
          "name":"host2",				//Domain Part will be appended automatically if not included
          "content":"2001:0db8:::::0370:7334",	//content is the IPv6 address
          "ttl":480					//ttl value is in minutes 480 = 6 hours
       }
    }
    

    4. Add CNAME Record (Alias)

    Example JSON File to add CNAME Record. CNAME is canonical name to another hostname.

    {
       "domain":"example.com",
       "add":{
          "type":"CNAME",
          "name":"mail",			//this actually setup mail.example.com points to mail.yahoo.com
          "content":"mail.yahoo.com",	//content is the canonical host name
          "ttl":480				//ttl value is in minutes 480 = 6 hours
       }
    }
    

    5. Add MX Record

    Example JSON File to add MX Record. MX defines the mail server that will receive Emails for the domain or mail zone

    {
      "domain": "example.com",
      "add":{
        "type": "MX",
        "mail-zone":"",		// "" is for Emails to @example.com. With value say "sub", will be for Emails for @sub.example.com
        "mail-server": "mail.dnsexit.com",
        "priority": 1,		// the lower value has higher priority; therefore, the MX with lowest value will become the primary MX
        "ttl": 480,
        "overwrite": true  // *filed optional. Default "false" unless defined. If true, it will just overwrite the existing definition
      }
    }
    
    

    Examples - Let's Encrypt TXT

    1. Add TXT for Wildcard SSL

    Example JSON File setup TXT for Let's Encrypt SSL Verification for wild card *.example.com

    {
      "domain": "example.com",
      "add":{
        "type": "TXT",
        "name": "_acme-challenge",	//take the acme.sh name as example. Could be other name if you use other programs
        "content": "fRPVGlc-jnuzb8CB6ATZUQ6Inp0Dj6V5Qgv7ScT6rB8",
        "ttl": 0,
        "overwrite": true
      }
    }
    

    2. Add TXT for Domain SSL

    Example JSON File setup TXT for Let's Encrypt SSL Verification for the example.com and www.example.com

    {
       "domain":"example.com",
       "add":[
          {
             "type":"TXT",
             "name":"_acme-challenge",	//take the acme.sh name as example. Could be other name if you use other programs
             "content":"ATZUQ6Inp0Dj6V5Qgv7ScT6rB8",
             "ttl":0,
             "overwrite":true
          },
          {
             "type":"TXT",
             "name":"_acme-challenge.www",	//take the acme.sh name as example. Could be other name if you use other programs
             "content":"_fFbVaP0gzAZsb9wOx__Kst9SWM",
             "ttl":0,
             "overwrite":true
          }
       ]
    }
    

    Update a Record

    1. Update the Domain's IP

    Example JSON File to update the Domain's IPv4 address to 1.1.1.100

    {
       "domain":"example.com",
       "update":{
          "type":"A",
          "name":"",			//name can be "example.com" instead
          "content":"1.1.1.100",		//content is the new IPv4 address of the domain
          "ttl":480				//ttl value is in minutes 480 = 6 hours
       }
    }
    

    2. Update CNAME (Alias)

    Example JSON File to update the CNAME of mail.example to mail.yahoo.com

    {
       "domain":"example.com",
       "update":{
          "type":"CNAME",
          "name":"mail",			//or "name":"mail.example.com"
          "content":"mail.yahoo.com",	//point to mail.yahoo.com instead
          "ttl":480				//ttl value is in minutes 480 = 6 hours
       }
    }
    

    2. Update MX

    Example JSON File to update the MX of mail.example to new TTL and Priority Number

    {
       "domain":"example.com",
       "update":{
          "type":"MX",
          "mail-server":"mail",		//or "name":"mail.example.com"
          "priority":1,		
          "ttl":880				//ttl value is in minutes 
       }
    }
    

    Delete a Record

    1. Delete CNAME

    Example JSON File to delete CNAME record mail.example.com

    {
       "domain":"example.com",
       "delete":{
          "type":"CNAME",
          "name":"mail"  //instead you can put mail.example.com
       }
    }
    

    1. Delete MX

    Example JSON File to delete MX record mail.example.com

    {
       "domain":"example.com",
       "delete":{
          "type":"MX",
          "name":"mail"  //instead you can put mail.example.com
       }
    }
    

    Advanced - Multiple Actions

    Create DNS for a Domain (multi-records)

    Example creat DNS for a domain to have A (Host), CNAME (Alias), and 2 MX Records. You put the value "new-dns":"true" to indicate the request is to create new DNS


    Note: "name":"", "content":"1.2.2.2" will assign the domain to have IP 1.2.2.2. Alternatively, you have put "name":"example.com" instead.
    {
       "new-dns":"true",
       "domain":"911domain.com",
       "add":[
          {
             "type":"A",
             "name":"",
             "content":"1.2.2.2"
          }, 
          {
             "type":"CNAME",
             "name":"www",
             "content":"911domain.com"
          }, 
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail1.dnsexit.com",
             "priority":1,
             "ttl":480,
             "overwrite":true
          }, 
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail2.dnsexit.com",
             "priority":2,
             "ttl":480,
             "overwrite":true
          }  
       ]  
    }  
    

    Add Multiple Records

    Example to add A (Host), CNAME (Alias), and 2 MX Records

    {
       "domain":"example.com",
       "add":[
          {
             "type":"A",
             "name":"host1",
             "content":"1.2.2.2"
          },
          {
             "type":"CNAME",
             "name":"yahoomail",
             "content":"mail.yahoo.com"
          },
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail1.dnsexit.com",
             "priority":1,
             "ttl":480,
             "overwrite":true
          },
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail2.dnsexit.com",
             "priority":2,
             "ttl":480,
             "overwrite":true
          }
       ]
    }
    

    Update Multiple Records

    {
       "domain":"example.com",
       "update":[
          {
             "type":"A",
             "name":"host1",
             "content":"1.2.2.2"
          },
          {
             "type":"CNAME",
             "name":"mail",
             "content":"mail.yahoo.com"
          },
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail1.dnsexit.com",
             "priority":1,
             "ttl":480,
          }      
       ]
    }
    

    Delete Multiple Records

    {
       "domain":"example.com",
       "delete":[
          {
             "type":"A",
             "name":"host1"
          },
          {
             "type":"CNAME",
             "name":"mail"
          }
       ]
    }
    

    Mixed Add/Update/Delete

    {
       "domain":"example.com",
       "add":[
          {
             "type":"A",
             "name":"host1",
             "content":"1.1.1.1"
          },
          {
             "type":"CNAME",
             "name":"mail2",
             "content":"mail2.yahoo.com"
          }
       ],
       "update":[
          {
             "type":"A",
             "name":"host2",
             "content":"1.1.1.2"
          },
          {
             "type":"CNAME",
             "name":"mail",
             "content":"mail.yahoo.com"
          },
          {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail1.example.com",  //you can set it as "mail-server":"mail1" instead
             "priority":1,
             "ttl":480,
          }     
       ],
       "delete":[
          {
             "type":"A",
             "name":"host3"
          },
          {
             "type":"TXT",
             "name":"spf"
          },
    	  {
             "type":"MX",
             "mail-zone":"",
             "mail-server":"mail3.dnsexit.com"
          }        
       ]
    }