API V1 DOCUMENTATION

The YDNS update API should work with most legacy dynamic DNS updaters. Update calls are performed by issuing simple HTTP GET requests to the following resources. All requests must use an HTTP authorization header with your account details (if using a native account), or using the API username and password which can be found here.

Table of Content
  1. Performing update calls
    1. Parameters
    2. Examples
    3. Return Codes
  2. IP Address retrieval

Performing update calls

To perform update calls, you can use the resource below. The use of https is recommended, but some older updater clients don't support TLS connections. That's why you can also use http if you wish.

Update URLhttps://ydns.io/api/v1/update/
Parameters

The following parameters can be used to control the behaviour of the update resource.

ParameterRequiredTypeValueDescription
hostyesstringexample.ydns.ioYour YDNS hostname you'd like to update.
ipnoIP AddressExample: 127.0.0.1 or ::1If this parameter is present, it will override the updater script to use that IP Address instead of REMOTE_ADDR it receives from the web server. The IP Address can either be a IPv4 or IPv6 address in the standard notation.
record_idnointegerExample: 1234If this parameter is present, it will force to update the specified record instead of trying to lookup best suitable one. If you have multiple records on your hosts, you can use that to specify which record to update.
Examples

https://ydns.io/api/v1/update/?host=example.ydns.io
Update the IP address of host "example.ydns.io" with the IP Address as seen by the web server.

https://ydns.io/api/v1/update/?host=example.ydns.io&ip=123.45.67.89
Update the IP address of host "example.ydns.io" with IPv4 Address "123.45.67.89".

https://ydns.io/api/v1/update/?host=example.ydns.io&record_id=1234
Update the Content of host "example.ydns.io" with the IP Address as seen by the web server.

Return Codes

On successful update requests, the update resource will return a HTTP status code 200 with the response content "good". On errors, the following HTTP error codes are returned with the appropriate error messages in the response content:

HTTP status codeDescription
400The action could not be performed due to invalid input parameters.
401The action could not be performed due to authentication issues.
404The action could not be performed because the host you'd like to update cannot be found.
IP Address retrieval

You can query the public IP address as seen by YDNS with the following endpoint:

IP Retrieval URLhttps://ydns.io/api/v1/ip

It will return your public IP address as string. If you'd like to get the response as JSON, you can append .json to endpoint:

IP Retrieval URL (JSON version)https://ydns.io/api/v1/ip.json

An example response would be:

{"ip": "111.111.111.111", "address_type": 4}

The address_type field is 4 when an IPv4 address has been detected or 6 for an IPv6 address.