API specification

Three ways to update a record — pick whichever your tool already speaks. Base URL https://loondns.com. All endpoints are HTTPS.

Authentication

Every update needs a token (create one in the dashboard or CLI). Tokens are either host-scoped (can change one name) or account-wide (any of your names). Pass it as a query param, HTTP Basic password, or Bearer header depending on the endpoint below.

1 · DuckDNS-compatible GET /update

Drop-in compatible with DuckDNS clients — just change the host to loondns.com.

Param	Required	Meaning
`domains`	yes	Comma-separated name(s), the label only (e.g. `home`).
`token`	yes	Your update token.
`ip`	no	IPv4 to set. Omit to auto-detect from your source IP.
`ipv6`	no	IPv6 (AAAA) to set.
`txt`	no	Set the `_acme-challenge` TXT (for Let's Encrypt).
`clear`	no	`true` clears the record (with `txt`, clears the TXT).
`verbose`	no	`true` returns extra lines (IP + UPDATED/NOCHANGE).

Responses: OK on success, KO on failure.

curl "https://loondns.com/update?domains=home&token=YOUR_TOKEN&ip=203.0.113.7" # auto-detect your public IP (no ip= param): curl "https://loondns.com/update?domains=home&token=YOUR_TOKEN"

2 · dyndns2 GET /nic/update

The standard protocol routers, ddclient, OPNsense and pfSense already speak.

Param	Required	Meaning
`hostname`	yes	Name label (or full FQDN).
`myip`	no	IP(s) to set, comma-separated v4/v6. Omit to auto-detect.

Auth: HTTP Basic (any username, password = token) or ?token=. Responses: good <ip>, nochg <ip>, nohost, badauth, notfqdn, abuse, 911.

curl -u "any:YOUR_TOKEN" "https://loondns.com/nic/update?hostname=home&myip=203.0.113.7"

3 · REST /api/v1

Clean JSON API. Auth: Authorization: Bearer YOUR_TOKEN.

Method & path	Does
`GET /api/v1/whoami`	Token owner & scope.
`GET /api/v1/hosts`	List your names & records.
`POST /api/v1/hosts`	Create a name. Body `{"name":"home"}` (account token).
`PUT /api/v1/hosts/{name}/ip`	Set A/AAAA. Body `{"ip":"203.0.113.7"}`.
`PUT /api/v1/hosts/{name}/txt`	Set/clear ACME TXT. Body `{"value":"..."}` (null clears).

curl -X PUT "https://loondns.com/api/v1/hosts/home/ip" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"ip":"203.0.113.7"}'

Records & behaviour

Types: A, AAAA, TXT. (Address family is auto-detected when you set an IP.)
Wildcard: *.home.loondns.com resolves to home's address automatically.
Let's Encrypt: set the TXT and it's served at _acme-challenge.<name>.loondns.com for DNS-01.
TTL: 60s — updates are live on the next query.
Rate limits: 30 updates/min per name.

See the setup guide for copy-paste configs, or the FAQ.