Don't want to handle your DNS record from the Web? Keep reading!

APIWe 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!