API Version 1

Fully DuckDNS-Compatible — Simple Migration

Back to API Overview
Overview

PuffinDNS offers a drop-in replacement for DuckDNS. The V1 API is fully compatible with DuckDNS, so if you already use DuckDNS in scripts, routers, or applications, you can migrate by simply replacing duckdns.org with puffindns.org.

DuckDNS Migration Simply change the domain of your API call: duckdns.org → puffindns.org
A/AAAA Record Update API

Update your domain(s) with a single HTTPS GET request:

https://www.puffindns.org/update?domains={DOMAINS}&token={TOKEN}[&ip={IPV4/6}][&ipv6={IPV6}][&verbose=true][&clear=true]
Parameters
Parameter Required Description
domains Yes Comma-separated list of subdomains or FQDNs to update.
token Yes Your PuffinDNS Legacy V1 Account-wide token.
ip No IPv4 or IPv6 address. If omitted, your IPv4 address if connecting over IPv4.
ipv6 No Explicit IPv6 address. Auto-detect IPv6 not possible with V1 API.
verbose No If true, returns detailed status information.
clear No If true, clears both IPv4 and IPv6 records for the domain(s).
Example Request
https://www.puffindns.org/update?domains=myhome,router&token=12345678-abcd-1234-efgh-1234567890ab&ip=203.0.113.42&ipv6=2001:db8::1234
Example Responses
Normal Response:
OK
Verbose Response:
OK
203.0.113.42
2001:db8::1234
UPDATED
Verbose Response Line Breakdown
  1. OK
  2. Current IPv4 address (blank if none)
  3. Current IPv6 address (blank if none)
  4. UPDATED or NOCHANGE
Error Response:
KO
Minimal Path-Style Request (No Parameters)

For basic routers or IoT devices that cannot send query parameters:

https://www.puffindns.org/update/{DOMAIN}/{TOKEN}[/{IP}]
Restrictions
  • DOMAIN: Single subdomain (no commas)
  • TOKEN: Your account token
  • IP: Optional IPv4 or IPv6 address. If omitted, IPv4 is auto-detected if connecting via IPv4.
TXT Record Update API

TXT records apply to the base subdomain and all sub-subdomains (e.g. xxx.mysub.puffindns.org shares the same TXT record as mysub.puffindns.org).

https://www.puffindns.org/update?domains={DOMAINS}&token={TOKEN}&txt={TEXT}[&verbose=true][&clear=true]
Parameters
Parameter Required Description
domains Yes Comma-separated list of subdomains.
token Yes Your account token.
txt Yes (unless clear=true) TXT record value.
verbose No If true, returns current TXT value and update status.
clear No If true, clears TXT record (ignores txt).
Example Response

Verbose mode example:

OK
sometxt=thistext
UPDATED
Migrating from DuckDNS

Migration is simple:

No code changes needed other than replacing the base domain (you may need to change the subdomain you reference depending on what you have registered on PuffinDNS):

duckdns.org  →  puffindns.org

All parameters, request formats, and responses are identical to DuckDNS.

Works with existing: scripts, cron jobs, routers, and ACME clients (e.g. certbot) without modification.
Quick Actions
Manage V1 Token View V2 API Back to Dashboard
Migration Tips
  • Replace duckdns.org with puffindns.org
  • Keep all existing parameters
  • No script modifications needed
  • Works with routers and IoT devices