Don't want to handle your DNS record from the Web? Keep reading!
We provide an API which you can use to interact with your account. The only thing you need to do is to send a POST request to an address with some parameters and this way you can handle your account and any records associated to it! The API is free both for free and Premium accounts and provide the same functionalities, but a Premium account allows you more host changes per day and handling a bigger family of DNS records. Security is very important to us, that's why we use SSL so your account and DNS details will travel safe accross the internet.
There are just a few rules to follow:
- Any request will be answered with a HTML-form return code and a status message.
- If the request was successful, a 200 OK duple will be returned
- If the request was unsuccessful, a 401 error code will be returned along with the error message that caused the failure
- If you send a request with the same values that you already have in the database (i.e., update is not needed), it will not be logged as an update attempt
- You can send up to 60 requests per hour (a cron per minute is ok). Above that, your IP address might be blocked and if abuse persist, your accound will be deleted.
- Remember: 2 updates per day and per host for free accounts, and 15 updates per day and per host for Premium accounts
How to make requests with the API?
There are some parameters you need to send along with the request. Others are optional.
| Parameter | Description | Mandatory? |
|---|---|---|
| username | Your username in the system (i.e., the one that you chose when creating an account) | Yes |
| password | Your password | Yes |
| host | The host whose record you want to change. If you created foo.freedns.io, the value for it would be foo | Yes |
| record | The record that you want to update. Only A, AAAA, CNAME, TXT and MX values are permitted (and the 3 last ones only allowed for Premium accounts.) | Yes |
| value | The new value for the record of the host defined above. If not defined, the user's IP address from which they did the request will be used as default - This is only applicable to A and AAAA records. For the rest of them, its specification is mandatory for adding/modifying a record. | No for A and AAAA records. Yes for CNAME, TXT and MX records. |
| preference | Only needed when updating MX records. 10 by default. | No |
| replace | Only needed if updating MX records. If set, the MX record with this value will be overriden by the one specified in the value parameter. | No |
| delete | Boolean. If set to 1, the record will be deleted instead of updated. Note that still a value parameter is needed, even if set to a blank value when deleting A, AAAA, CNAME and TXT records, and the value to be deleted when the record is MX. | No |
What programming languages can I use to interact with the API?
Any that supports making HTTP(S) POST requests. There are plenty of them, and nowadays most of the modern programming languages support this operation.
Are there any samples that I might already use?
Yes. We have a GitHub repository with several examples. Most of them are prepared to simply replace their connection values and run!
I implemented some examples in my favorite language and it's not on your GitHub repository. Would you like to add it?
Of course!. Please, fork our repo, make a pull request and we will be glad to add those files to our repo. It would be awesome if you could take the header comments of all the examples of an already uploaded programming language (Python, PHP...) and 'translate' them to the new language. Usually, only the 'params' array change, so changed one, changed all. Any contribution is very appreciated!
What about routers? Do you support the DynDNS feature on them?
That depends on your router. Some of them have some of the most relevant DynDNS servers already built-in in a combobox and they won't allow you adding your own. However, if you're able to specify your own server, we support that feature! Just fill in the URL you'll find below as the update request URL and it should work. A 200 OK code will be returned upon success. A 401 code will be returned if something went wrong along with the error message. Anyhow, if you have any doubts don't hesitate to write us and we'll help as much as we can (maybe we can even write a custom API for your router if needed and possible).
The URL should look like this: https://freedns.io/nic/update?username=<username>&password=<pass>&host=<domain>&myip=<ipaddr>
Make sure to specify only the hostname in the host field, not the full host (example: write foo instead of foo.freedns.io).
Is any other way to update my host?
We have a Docker image on Docker Hub that can do all the work for you! It's an alpine based image, so it's very small in size. The fast way of running it is
docker container run -d --name freedns-update --rm -e username=your_freedns_username -e password=your_freedns_password -e host=your_host freedns/freedns-update
Still, if you want to get a full list of parameters, you'll find all the documentation on the Docker Hub's page. However, if you find any further issues or need help with running the container, don't hesitate to contact us.