Skip to content

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

idstringrequired
The domain ID (dom_…).

Body

hostnamestringrequired
The full host name to update, in lower case and without a trailing dot: the domain itself or a name under it, such as home.example.com.
recordTypestring
A for IPv4 or AAAA for IPv6. Default A. One of A, AAAA.

Example

POST /api/v2/domains/{id}/dyndns
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"
}'

Responses

201 The new configuration, with its token.

Response 201
{
"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
idstring
The DynDNS configuration ID (ddns_…).
hostnamestring
The full host name the configuration updates, such as home.example.com.
recordTypestring
A for IPv4 or AAAA for IPv6. One of A, AAAA.
tokenstring | null
The secret your router or DynDNS client sends with each update.
lastIpstring | null
The address set by the last update. Null before the first update.
lastUpdatedAtstring | null
When the last update was made.
updateCountinteger
How many updates have been made.
enabledboolean
Whether updates are accepted.
createdAtstring | null
When the configuration was created.
updatedAtstring | null
When the configuration was last changed.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The 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.
401Unauthorized. Authentication is required.
403The key does not have write:domains (forbidden). requiredScopes lists the missing scope. A domain that is not in your account answers 404.
404The domain was not found or is not in your account (domain_not_found).
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.