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

ForgeDNS

Free dynamic DNS. One API call.

Get Started API Reference

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.

Quick Start

# get API key (verify via email)
curl -s -X POST https://api.forgedns.com/v1/api-keys \
    -H "Content-Type: application/json" \
    -d '{"name": "Your Name", "email": "you@example.com"}'

# 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"

API Reference

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

► POST /api-keys

Creates a new API key. No authentication required. The key is emailed to you.

Note: New keys must be confirmed via the link in the email before they can be used.

Request Body (JSON)

Parameter Type Required Description
name string Yes Your company or personal name
email string Yes Address to receive the API key

Examples

$ curl -s -X POST https://api.forgedns.com/v1/api-keys \
    -H "Content-Type: application/json" \
    -d '{"name": "Bob Smith, TechCorp", "email": "you@example.com"}'

{"api_key": "YOUR_API_KEY"}
► PUT /domains/{subdomain}

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"}
► GET /domains

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}
]}
► DELETE /domains/{subdomain}

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"}
▶ 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.