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 3.145.163.138.
- 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 3.145.163.138). 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.