Create a DynDNS configuration
POST /api/v2/domains/{id}/dyndns
Creates a dynamic DNS (DynDNS) configuration for a host name on the domain. The response holds the token that a router or DynDNS client uses to update the host’s A or AAAA record. Creating the configuration does not change DNS. The first update changes the host’s A or AAAA record. When there is none it creates one with a TTL of 300 seconds. Updates reach the domain only when it uses Hostup nameservers (available on GET /api/v2/domains/{id}/dyndns). This call does not check that and creates the configuration either way, so check available first.
The client calls https://cloud.hostup.se/api/dyndns/update?hostname=home.example.com&token=<token>&ip=198.51.100.45 with GET. POST works too, but the values stay in the query string; myip is accepted instead of ip. Without ip the address the request comes from is used, so for an AAAA host send the IPv6 address in ip unless the client connects over IPv6. Routers with a DynDNS2 setting use cloud.hostup.se/nic/update with the host name as user name and the token as password.
The update reply is plain text: good <ip> or nochg <ip> on success, badauth for a wrong token or host name, abuse when the configuration is turned off or the token sent more than 20 updates in a minute, 911 for an address that does not fit the record type, and dnserr when the record could not be written.
Keep the token secret. Anyone with it can change the host’s address. No endpoint changes a token. To replace one, delete the configuration and create it again; the new configuration gets a new ID and token.
Authentication: An API key with the scope write:domains. About keys and scopes
Request
Path parameters
idstringrequireddom_…).Body
hostnamestringrequiredhome.example.com.recordTypestringA for IPv4 or AAAA for IPv6. Default A. One of A, AAAA.Example
curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/dyndns" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "hostname": "home.example.com", "recordType": "A" }'curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/dyndns" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "hostname": "ipv6.example.com", "recordType": "AAAA" }'Responses
201 The new configuration, with its token.
{ "id": "ddns_01hxa3b4c5d6e7f8g9h0j1k2m3", "hostname": "home.example.com", "recordType": "A", "token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "lastIp": null, "lastUpdatedAt": null, "updateCount": 0, "enabled": true, "createdAt": "2026-04-27T12:00:00.000Z", "updatedAt": null}Response fields
idstringddns_…).hostnamestringhome.example.com.recordTypestringA for IPv4 or AAAA for IPv6. One of A, AAAA.tokenstring | nulllastIpstring | nulllastUpdatedAtstring | nullupdateCountintegerenabledbooleancreatedAtstring | nullupdatedAtstring | nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The body is not valid (invalid_request). A missing hostname or a recordType other than A or AAAA names the field in errors[].pointer. A hostname that is neither the domain nor a name under it, and a configuration that already exists for the same host name and type, both return only detail “The request is invalid.” with no errors entry. Check the host name, then look for an existing configuration with GET /api/v2/domains/{id}/dyndns. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The key does not have write:domains (forbidden). requiredScopes lists the missing scope. A domain that is not in your account answers 404. |
| 404 | The domain was not found or is not in your account (domain_not_found). |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |