DDNS guide: update records from scripts

Create your domain in the console, then keep any record current through the API — ideal for dynamic IPs.

This is one piece of the API — the full API documentation covers zone creation, record CRUD, wildcard-cert DNS-01 and everything else.

Step 1 · Create the domain

Sign in and add your domain (for example example.com) on the Zones page, then switch your registrar's NS records to the ones the platform assigns.

Step 2 · Create an API token

On the API Tokens page create a token with at least the records:write scope. Tokens can only ever touch your own zones.

Step 3 · One call updates the record

The DDNS endpoint upserts by hostname + type: the record is created if missing, replaced if the value changed, left alone if identical — perfect for repeated cron runs.

curl -X POST https://dns.us.wr.rs/api/v1/ddns \
  -H "Authorization: Bearer dcp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com","name":"home","type":"A","value":"203.0.113.7","ttl":60}'

Request parameters

Parameter	Description
`zone`	Zone name — optional. When omitted it is derived from the full hostname in "name".
`name`	Hostname to update: "home" (in-zone), "home.example.com" (full), or "@" for the zone apex.
`type`	Record type: A, AAAA, CNAME or TXT.
`value`	The new value (IPv4/IPv6 address, target hostname or text).
`ttl`	Optional TTL in seconds (minimum 30), default 300.

The response "action" is created / updated / unchanged; "record" echoes the effective record.

Automatic updates — Linux (cron)

The script below reads this machine's public IPv4 from the platform and calls the API; run it every few minutes from cron.

#!/bin/sh
# DDNS update: keep home.example.com pointed at this machine's IPv4.
TOKEN="dcp_xxxxxxxxxxxxxxxx"     # API token with records:write
NAME="home.example.com"          # full hostname to update

IP=$(curl -s https://dns.us.wr.rs/api/v1/ddns/ip | sed 's/.*"ip":"\([^"]*\)".*/\1/')
if [ -n "$IP" ]; then
  curl -s -X POST https://dns.us.wr.rs/api/v1/ddns \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"name\":\"$NAME\",\"type\":\"A\",\"value\":\"$IP\",\"ttl\":60}"
fi

crontab -e
*/5 * * * * /usr/local/bin/ddns-update.sh >/dev/null 2>&1

Windows (Task Scheduler + PowerShell)

# DDNS update (Windows Task Scheduler, every 5 minutes)
$token = "dcp_xxxxxxxxxxxxxxxx"
$name  = "home.example.com"
$api   = "https://dns.us.wr.rs"

$ip = (Invoke-RestMethod "$api/api/v1/ddns/ip").ip
Invoke-RestMethod -Method Post -Uri "$api/api/v1/ddns" `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body (@{ name = $name; type = "A"; value = $ip; ttl = 60 } | ConvertTo-Json)

Verify

After updating, check the authoritative answer with dig:

dig +short home.example.com @ns1.qn.cx

Tip: use a short TTL (60–300 s) on DDNS records so the world switches to the new address quickly.