DNS API
Do you have a domain name that needs to point to an IP address that changes (e.g. to your home PC)? Then you may want to use
our DNS API.
You can use the DNS API to set a domain's IP address.
You can also use the DNS API to automate setting up and changing Mail Server (MX), Text (TXT) records, etc. As well as
deleting records.
Some examples of using the API:
- Set the IP Address for 'example.com' to your PC's address. Right now that is 18.97.14.87.
- https://zonomi.com/app/dns/dyndns.jsp?host=example.com&api_key=apikeyvaluehere
- Set an IP Address (A) record
- https://zonomi.com/app/dns/dyndns.jsp?action=SET&name=example.com&value=10.0.0.1&type=A&api_key=apikeyvaluehere
- Delete an IP Address (A) record
- https://zonomi.com/app/dns/dyndns.jsp?action=DELETE&name=example.com&type=A&api_key=apikeyvaluehere
- Set an MX Record
- https://zonomi.com/app/dns/dyndns.jsp?action=SET&name=example.com&value=mail.example.com&type=MX&prio=5&api_key=apikeyvaluehere
- Retrieve a list of records with the specified name.
- https://zonomi.com/app/dns/dyndns.jsp?action=QUERY&name=example.com&api_key=apikeyvaluehere
- Retrieve all records ending in example.com. e.g. letting you fetch all records in a DNS zone.
- https://zonomi.com/app/dns/dyndns.jsp?action=QUERY&name=**.example.com&api_key=apikeyvaluehere
- Multiple actions: set two records to the same IP and delete the bar.example.com IP Address (A) record.
- https://zonomi.com/app/dns/dyndns.jsp?action[1]=SET&name[1]=example.com,bar.example.com&value[1]=10.0.0.1&action[2]=DELETE&host[2]=bar.example.com&api_key=apikeyvaluehere
- Multiple actions: set multiple different values for a particular name. e.g. for setting multiple MX servers (like with gmail).
- https://zonomi.com/app/dns/dyndns.jsp?action[1]=SET&name[1]=example.com&value[1]=ASPMX.L.GOOGLE.COM&prio[1]=1&type[1]=MX&action[2]=SET&name[2]=example.com&value[2]=ALT1.ASPMX.L.GOOGLE.COM&prio[2]=2&type[2]=MX&action[3]=SET&name[3]=example.com&value[3]=ALT2.ASPMX.L.GOOGLE.COM&prio[3]=3&type[3]=MX&action[4]=SET&name[4]=example.com&value[4]=ALT3.ASPMX.L.GOOGLE.COM&prio[4]=4&type[4]=MX&action[5]=SET&name[5]=example.com&value[5]=ALT4.ASPMX.L.GOOGLE.COM&prio[5]=5&type[5]=MX&api_key=apikeyvaluehere
- Setup a new DNS zone.
- https://zonomi.com/app/dns/addzone.jsp?name=example.com&api_key=apikeyvaluehere
- Delete a DNS zone.
- https://zonomi.com/app/dns/dyndns.jsp?action=DELETEZONE&name=example.com&api_key=apikeyvaluehere
- Return a list of zones on your account.
- https://zonomi.com/app/dns/dyndns.jsp?action=QUERYZONES&api_key=apikeyvaluehere
- Convert a zone to a slave zone with the specified master name server IP address.
- https://zonomi.com/app/dns/converttosecondary.jsp?name=example.com&master=0.0.0.0&api_key=apikeyvaluehere
- Convert a zone from a slave zone back to a 'regular' zone (where you manage your DNS records via our web pages and API).
- https://zonomi.com/app/dns/converttomaster.jsp?name=example.com&api_key=apikeyvaluehere
- Queue a zone refresh on slave zone.
- https://zonomi.com/app/dns/slavezonerefresh.jsp?name=example.com&api_key=apikeyvaluehere
- Change an IP across all your zones.
- https://zonomi.com/app/dns/ipchange.jsp?old_ip=0.0.0.0&new_ip=0.0.0.0&api_key=apikeyvaluehere
DNS API Reference
Parameter Name |
Parameter Alias |
Description |
action |
|
One of SET (the default), QUERY or DELETE. If you set a hostname that does not already exist in a zone, the
hostname will be added to that zone. If you delete a record that does not exist the request will be ignored. |
host |
hostname |
The dns record you are updating. This field is required. You must have a zone setup on our name servers
with this host in it. e.g. if you have an example.com zone setup you could have host=example.com or
host=www.example.com. This API will not create zones on the fly. The zone must not be a 'slave' zone on our
servers (in which case it is read-only). You can provide one or more (comma separated) host values. e.g. if you
wanted to set multiple domain names to a single IP addresss. Use **.example.com to match all names ending in
example.com. This can be useful for getting a list of all records in a zone. |
type |
|
DNS record type. e.g. A, MX, or TXT. Defaults to A. |
value |
myip, dnsto |
Set this value on the record. If the record is an IP Address (A) record then the value would need to be an IP
address. If the record were a Mail Server (MX) record then it would need to be a host name. For an IP Address (A)
record this will default to the IP address of the API client (e.g. your home PC, e.g. right now that is 18.97.14.87).
To set multiple values for a single hostname provide a comma separated list of values. e.g. if you wanted to set
multiple IPs for a IP Address (A) record. The multiple values feature only works with some (e.g. PTR, A, MX, CNAME)
record types. The IP Address (A) record cannot default to the IP address of the API client if that client is making a request
over IPv6. In that case you would need to specify the IP Address value or force the request over IPv4. e.g. by making the
request to ipv4.zonomi.com .
|
prio |
|
The priority. A number. Used on MX records. If not specified the API will set it to 0. If more
than one host name is specified for the action and the priority is not specified then the priority is incremented for each
host. |
ttl |
|
The TTL (time to live) on the record. Optional (and typically best not provided). A number. Used to
hint at how long in seconds recursive name servers should cache the record details. 3600 or one hour is a common
default. |
api_key |
|
Your DNS API key. Keep this secret (like you would a password). This API key is unique to your user
account. Your API key can be passed in as an api_key=blah parameter. Or it can be passed in as an 'Authorization'
header. The format for the Authorization header is like "Authorization: redrata api_key=ec7....82e137431". To
change your API key (e.g. if someone who should not know it discovers it) use our API keys page. You would need to be logged in to see your API key.
|
If you wish to perform more than one action add [number] to each parameter in that action set. The actions will be
performed in numerical order.
You can use either the https URL or a plain http URL. If your dynamic DNS client supports it, we recommend the https
URL since then the URL is encrypted.
You can use GET (with the parameters in the URL) or POST (with the parameters as form URL encoded values).
If the update is successful you will get page a page with one line of text that starts "OK:". If the update fails you
will get back a page with one line of text that starts "ERROR:".
API clients
Software supporting the DNS API:
- Certy a Dynamic DNS and Let's Encrypt certificate client.
- ddnsupdater for Windows
- cron plus wget (NB: put urls
inside single quotes with wget. Else your command line will interpret the & character as 'launch a background process').
- Many of these clients
work well.
- Vlad Alive has written a Zonomi Ruby gem
- Alvin Mites has written a python wrapper on github
- The Python RimuDNS library for RimuHosting and Zonomi name servers.
Supports exporting zones to Bind files.
- Zonomi-Bind-Export exports a Zone to a Bind file.
- cPanel WHMCS DNS manager to connect a cPanel install to Zonomi
- More to come. If your client is not supported, point the developer at this page and ask them to support our
service. Then let us know when it is done so we can link to them!
- LEGO (the LetsEncrypt client written in Go)
- Fritz!Box routers support DynDns.
- Go to Internet | Permit Access | DynDNS
- Tick DynDNS. Use User-defined as the DynDNS provider.
- Set an update URL of https://ipv4.zonomi.com/app/dns/dyndns.jsp?host=<domain>&api_key=<pass>
- Set a domain name of which domain name you wish to set. e.g. router.example.com
- Set the User name to anything (e.g. 'na'). This field is not required but mandatory.
- Set the password to the api key.