Dynamic DNS
HTTPS DynDNS-compatible updates for existing A and AAAA records on customer-owned DNScale zones.
Device update endpoint
GET https://api.dnscale.eu/nic/update is separate from the JSON /v1 API.
It uses HTTP Basic authentication: the dedicated DDNS credential ID as username
and its one-time secret as password. General API keys, browser sessions and
account passwords cannot authorize device updates.
Create the credential in your zone dashboard. It is restricted to one exact hostname and its selected A/AAAA types. The issuing user must remain active and retain write access to the zone. The zone must remain an active primary zone.
| Query parameter | Contract |
|---|---|
hostname | Required. One full hostname matching the credential; case and a single trailing dot are normalized. |
myip | One IPv4 or IPv6 address, or one of each separated by a comma. |
myipv4 | Explicit IPv4 address; may be combined with myipv6, but not myip. |
myipv6 | Explicit IPv6 address; may be combined with myipv4, but not myip. |
If no address parameter is supplied, the HTTPS connection address determines which family is updated. Omitted families remain untouched. Empty, duplicate, mismatched or malformed parameters are rejected. Private unicast addresses are supported; unspecified, loopback, multicast, link-local, scoped and IPv4-mapped IPv6 addresses are rejected. This endpoint never accepts credentials in query parameters, multiple hostnames, wildcard changes or MX changes.
For legacy dyndns2 compatibility, inert system=dyndns, wildcard=OFF/NOCHG,
mx=NOCHG, and backmx=NO/NOCHG parameters are accepted.
curl --user 'YOUR_CREDENTIAL_ID' --get \
'https://api.dnscale.eu/nic/update' \
--data-urlencode 'hostname=home.example.com' \
--data-urlencode 'myip=192.0.2.10,2001:db8::10'Curl prompts for the DDNS secret. Replace the example addresses before use.
Responses have Content-Type: text/plain and Cache-Control: no-store.
| HTTP | Body | Meaning |
|---|---|---|
| 200 | good IP | Requested updates completed in every serving region. |
| 200 | nochg IP | Requested addresses already matched in every region. |
| 401 | badauth | Invalid/revoked credentials or issuer no longer authorized. |
| 403 | badauth | HTTPS required. |
| 200 | nohost | Hostname or DNS configuration unavailable. |
| 200 | notfqdn | Invalid parameters/address or ungranted address family. |
| 429 | 911 | Throttled or another update is in progress; honor Retry-After. |
| 503 | 911 | Temporary backend failure; retry after at least 1,800 seconds. |
IP contains the submitted address or a comma-separated IPv4/IPv6 pair.
The persistent per-credential interval is 30 seconds. Check at five-minute
intervals and avoid unnecessary writes. Requests also have an edge per-IP limit.
A partial write across regions or address families is possible during a backend failure. It is never reported as success. Retry the same addresses to converge; there is no automatic rollback. A successful update does not guarantee that recursive resolvers have expired previous cached answers.
Dashboard management
These JSON endpoints require a signed-in browser session, zones:read and
records:write capabilities, and current tenant/zone write access. API keys,
including unrestricted keys, cannot create, list or revoke DDNS credentials.
Normal session-origin protections apply to mutations.
| Method | Path | Result |
|---|---|---|
| GET | /v1/zones/{zone_id}/ddns | Active credentials, allowed families, creation and last-success/change times. |
| POST | /v1/zones/{zone_id}/ddns | Creates a credential; returns its secret exactly once. |
| DELETE | /v1/zones/{zone_id}/ddns/{credential_id} | Revokes the credential after any in-flight update; leaves records untouched. |
Creation body:
{"hostname":"home.example.com","ipv4":true,"ipv6":true}Responses use the normal {"status":"success","data":...} envelope.
Creation data contains credential and secret; listing data contains
credentials; deletion data contains revoked: true. Credential metadata:
id, zone_id, user_id, hostname, ipv4, ipv6, created_at,
last_success_at, last_change_at. Timestamps are UTC; never-used fields are
null. Hashes are never returned. last_success_at advances for both good
and nochg. last_change_at advances only after successful changed writes.
Creation returns a configuration error if the zone is inactive/secondary, a selected RRset is missing/disabled/multi-valued, or a conflicting alias or subdomain delegation exists. A duplicate active hostname returns HTTP 409. There is no token recovery: revoke and create a replacement if the secret is lost.
Plans and limits
Basic DDNS is included in every existing plan with no separate fee or feature entitlement. It only changes the value of existing single-address records: zone count, record count, TTL, comments and query billing stay unchanged. Create records through the existing editor/API, where normal quotas apply. The documented minimum TTL remains 300 seconds.