API documentation
Base URL https://api.dns-me.com. Machine readable OpenAPI:
/openapi/v1.json.
Names & authentication
Every device has a single-label name below dns-me.com, e.g. sensor-42.dns-me.com.
Names may contain a-z 0-9 - _ (max. 63 characters, case-insensitive).
| Device type | Password / secret |
|---|---|
| Single device | The secret shown when the device was created in the dashboard. |
| Device of a group | base64(sha256(utf8(lower(name)) ‖ hex_decode(masterKey)))Name is <prefix>_<id> without the domain. The device is created on its first update. |
The v2 API accepts the secret as Authorization: Bearer <secret> or as HTTP Basic auth
(<name>:<secret>). After 10 failed attempts a client is blocked for 10 minutes.
REST API v2
POST /v2/devices/{name}/update
Sets the addresses of a device. Without a body, the IP of the caller is used. With a JSON body, every given
field is applied: an address, "auto" (caller IP) or null (remove). Omitted fields stay unchanged.
curl -X POST https://api.dns-me.com/v2/devices/sensor-42/update \
-H "Authorization: Bearer $SECRET" -H "Content-Type: application/json" \
-d '{"ipv4":"192.168.1.42","ipv6":"auto"}'
{"name":"sensor-42","fqdn":"sensor-42.dns-me.com","ipv4":"192.168.1.42",
"ipv6":"2001:db8::42","changed":true,"updatedAt":"2026-11-09T14:00:00+00:00"}Responses: 200 ok, 400 invalid address, 401 wrong secret,
429 too many updates (max. 30 per device and minute).
GET /v2/devices/{name}
Returns the current DNS state of the device (device auth).
PUT /v2/devices/{name}/acme · DELETE /v2/devices/{name}/acme
Publishes the TXT record _acme-challenge.{name}.dns-me.com for ACME DNS-01 validation, so a device
can obtain a Let's Encrypt certificate for its name – even if it only has a LAN address. Body:
{"value":"<key authorization digest>"}. Up to 4 values, each valid for 15 minutes.
DELETE removes one value (?value=) or all.
Note: certificate authorities don't issue certificates for names containing _; use
names with - for devices that need TLS.
GET /v2/myip
Returns the public IP the request came from: {"ip":"203.0.113.7"}.
dyndns2 protocol
Compatible with routers and tools speaking the DynDNS/No-IP protocol (FRITZ!Box, OpenWrt, ddclient, inadyn, ESPHome …).
GET https://api.dns-me.com/nic/update?hostname=sensor-42.dns-me.com&myip=192.168.1.42,2001:db8::42 Authorization: Basic base64(sensor-42:SECRET)
| Response | Meaning |
|---|---|
good <ip> | updated |
nochg <ip> | address unchanged |
badauth | wrong name / secret |
notfqdn / dnserr | invalid hostname / invalid address |
abuse | rate limited |
myip is optional (default: caller IP) and may contain an IPv4 and an IPv6 address separated by a comma;
myipv6 is accepted too.
Legacy API (2017)
Still supported unchanged – also over plain HTTP at http://api.dns-me.com for older devices.
New integrations should use v2 over HTTPS.
GET /api/Update?url={name}&password={password}
Sets the address of the caller's IP family. Returns 204.
POST /api/Update
{"DeviceUrl":"smart-me_12345678.dns-me.com","Password":"…","IpV4":"192.168.1.42","IpV6":null}JSON or form encoded. IpV4/IpV6 replace both records; null removes one. Returns 204.
DNS
The name servers are authoritative for dns-me.com only (no recursion). Device records have a TTL of
60 seconds; names that don't exist return NXDOMAIN. Supported: A, AAAA, TXT (ACME), SOA, NS, CAA,
EDNS0, TCP, AXFR to configured secondaries and NOTIFY.