Table of Contents
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 |
| Simply run curl or wget command to update your dynamic IP for any hosts or domains under your account. |
>> curl https://api.dnsexit.com/dns/ud/?apikey=API-KEY -d host=host1.domain.com,host2.domain2.com |
| On any machine behind the router, just schedule a job to run the above command every few minutes. Our system will automatically detect your public IP address and update your hosts to the new IP. Alternatively, you may add parameter -d ip=xx.xx.xx.xx to overwrite the IP. For multiple hosts, just seperate them by , (comma). The API Key can be generated 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. |
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/
Example to update domain IP address
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 |
>> 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 |
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 likeNote: 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 DNSNote: "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"
}
]
}