ForgeDNS — Free Dynamic DNS API

What is ForgeDNS?

ForgeDNS gives you a free subdomain under forgedns.com that you can point to any IP address or hostname — instantly, via a simple REST API.

Perfect for home servers, dev machines, Raspberry Pis, or anything behind a dynamic IP. No account signup, no dashboard — just an API key and a few commands.

Pass an IP address and get an A record. Pass a hostname and get a CNAME. ForgeDNS figures out the rest. Works great with HTTPie or plain curl.

If you own your own domain, you can point a CNAME at your ForgeDNS entry — so visitors only ever see your domain. For example, add a home.coad.net CNAME pointing to noahhome.forgedns.com. Users hit home.coad.net, and you update the ForgeDNS entry whenever your IP changes — your domain always follows.

Get Your API Key

Enter your details below. We'll email you a verification link — click it to activate and reveal your API key.

Quick Start

Once you have your API key, set a domain name with a single command.

# set a domain name to your current ip
curl -s -X PUT https://api.forgedns.com/v1/domains/myserver \
    -H "x-api-key: YOUR_API_KEY"

# set a domain name to your current ip
http PUT https://api.forgedns.com/v1/domains/myserver x-api-key:YOUR_API_KEY

API Reference

Base URL: https://api.forgedns.com/v1 · Auth: x-api-key header

To get an API key, use the form above.

► PUT /domains/{subdomain} Create or update a DNS record

Creates or updates a DNS record. Pass an IP address (A record) or hostname (CNAME). Omit address to use the caller's IP automatically. Maximum 5 domains per API key.

Headers

Header	Required	Description
x-api-key	Yes	Your ForgeDNS API key

Request Body (JSON)

Parameter	Required	Description
address	No	IP address (→ A record) or hostname (→ CNAME). Defaults to caller's IP.

Path

Segment	Description
{subdomain}	4–30 chars, alphanumeric + hyphens. Accepts `myhost` or `myhost.forgedns.com`

Examples

# auto-detect your IP:
$ curl -s -X PUT https://api.forgedns.com/v1/domains/myserver \
    -H "x-api-key: YOUR_API_KEY"

{"domain": "myserver.forgedns.com", "address": "203.0.113.42", "record_type": "A"}

# specify target IP address:
$ curl -s -X PUT https://api.forgedns.com/v1/domains/myserver \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"address": "1.2.3.4"}'

{"domain": "myserver.forgedns.com", "address": "1.2.3.4", "record_type": "A"}

# CNAME record (pass a hostname instead of IP):
$ curl -s -X PUT https://api.forgedns.com/v1/domains/www \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"address": "example.com"}'

{"domain": "www.forgedns.com", "address": "example.com", "record_type": "CNAME"}

# auto-detect your IP:
$ http PUT https://api.forgedns.com/v1/domains/myserver \
    x-api-key:YOUR_API_KEY

{"domain": "myserver.forgedns.com", "address": "203.0.113.42", "record_type": "A"}

# specify target IP address:
$ http PUT https://api.forgedns.com/v1/domains/myserver \
    x-api-key:YOUR_API_KEY address=1.2.3.4

{"domain": "myserver.forgedns.com", "address": "1.2.3.4", "record_type": "A"}

# CNAME record (pass a hostname instead of IP):
$ http PUT https://api.forgedns.com/v1/domains/www \
    x-api-key:YOUR_API_KEY address=example.com

{"domain": "www.forgedns.com", "address": "example.com", "record_type": "CNAME"}

► GET /domains List your subdomains

Returns all subdomains registered to your API key.

Headers

Header	Required	Description
x-api-key	Yes	Your ForgeDNS API key

Examples

$ curl -s https://api.forgedns.com/v1/domains \
    -H "x-api-key: YOUR_API_KEY"

{"domains": [
  {"domain": "myserver.forgedns.com", "address": "1.2.3.4", "record_type": "A", "last_updated": 1774480071},
  {"domain": "www.forgedns.com", "address": "example.com", "record_type": "CNAME", "last_updated": 1773980040}
]}

$ http https://api.forgedns.com/v1/domains \
    x-api-key:YOUR_API_KEY

{"domains": [
  {"domain": "myserver.forgedns.com", "address": "1.2.3.4", "record_type": "A", "last_updated": 1774480071},
  {"domain": "www.forgedns.com", "address": "example.com", "record_type": "CNAME", "last_updated": 1773980040}
]}

► DELETE /domains/{subdomain} Delete a DNS record

Permanently removes a subdomain and its DNS record.

Headers

Header	Required	Description
x-api-key	Yes	Your ForgeDNS API key

Examples

$ curl -s -X DELETE https://api.forgedns.com/v1/domains/myserver \
    -H "x-api-key: YOUR_API_KEY"

{"message": "Domain removed myserver.forgedns.com"}

$ http DELETE https://api.forgedns.com/v1/domains/myserver \
    x-api-key:YOUR_API_KEY

{"message": "Domain removed myserver.forgedns.com"}

▶ Pro Tip — keep your IP current with a cron job

Add a crontab entry to automatically update your subdomain every hour, so your DNS stays in sync even when your IP changes.

terminal

$ crontab -e

add this line

# update myserver.forgedns.com every hour
0 * * * * curl -s -X PUT https://api.forgedns.com/v1/domains/myserver -H "x-api-key: YOUR_API_KEY" > /dev/null 2>&1

The address is omitted, so ForgeDNS automatically uses the machine's outbound IP.

Limits & Rules

5

Subdomains per API key

4–30

Character limit for subdomain names

a-z 0-9 -

Allowed characters (no leading/trailing hyphens)

IPv4 only

IPv6 is not currently supported

6 mo

Domains expire after 6 months without an update and are released for re-registration

ForgeDNS is a free service. Accounts showing signs of abuse, excessive automated use, or remain unclaimed may be removed without notice.