ipn.fyi Documentation

Free dynamic DNS for any device. Point a stable hostname like you.n.ipn.fyi to your changing IP address — updated via a simple API call.

Overview

ipn.fyi is a dynamic DNS service powered by DNS Science. Every registered user gets a subdomain under n.ipn.fyi that they can update any time their IP changes.

Free, no credit card required
IPv4 and IPv6 support
REST API — one curl command to update
250-entry IP change history per domain
CLI client for Linux, macOS, Windows

Quick Start

Register an account

curl -X POST https://ipn.fyi/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"yourname","password":"s3cure!"}'

You get back an api_key. Save it.

Update your IP

curl -X POST https://ipn.fyi/api/update \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"yourname","ipv4":"1.2.3.4"}'

Your hostname is live

Once DNS updates propagate (~60s), yourname.n.ipn.fyi resolves to your IP.

Concepts

Domains

Each user owns one domain under n.ipn.fyi matching their username. Your username alice gets alice.n.ipn.fyi. Admin keys can manage any domain.

API Keys

All API calls (except register/login/health) require an X-API-Key header or a ?key= query parameter. Your key is shown once on register and retrievable via login.

TTL

All records have a 300-second (5 minute) TTL. After updating your IP, propagation takes up to 5 minutes.

Authentication

Pass your API key on every request (except auth endpoints) via header or query param:

# Header (preferred)
X-API-Key: YOUR_API_KEY

# Query param (for simple GET scripts)
?key=YOUR_API_KEY

Register

POST /api/auth/register No auth required

Field	Type	Notes
username	string	Letters, numbers, hyphens. Becomes your subdomain. required
password	string	Minimum 8 characters. required
email	string	Optional contact address. optional

// Response 201
{
  "success": true,
  "username": "yourname",
  "api_key": "a1b2c3...",
  "domain": "yourname.n.ipn.fyi"
}

POST /api/auth/login No auth required

Field	Type	Notes
username	string	required
password	string	required

// Response 200
{ "success": true, "username": "yourname", "api_key": "a1b2c3..." }

Update IP

POST /api/update API key

Field	Type	Notes
domain	string	Your username / subdomain label. required
ipv4	string	IPv4 address. optional*
ipv6	string	IPv6 address. optional*
comments	string	Free-form note. optional

* At least one of ipv4 or ipv6 is required.

// Response 200
{
  "success": true,
  "domain": "yourname.n.ipn.fyi",
  "ipv4": "1.2.3.4",
  "ipv6": null,
  "updated_at": 1714000000
}

GET /api/update Query param shorthand

GET /api/update?key=YOUR_KEY&domain=yourname&ipv4=1.2.3.4

Records

GET /api/records API key

Optional: ?domain=yourname to filter to a single record.

// Response 200
{
  "records": [
    {
      "domain": "yourname",
      "current_ipv4": "1.2.3.4",
      "current_ipv6": null,
      "updated_at": 1714000000,
      "version": 12
    }
  ]
}

History

GET /api/history API key

Optional: ?domain=yourname&limit=50

// Response 200
{
  "history": [
    { "domain": "yourname", "ipv4": "1.2.3.4", "changed_at": 1714000000, "change_type": "ipv4_change" }
  ]
}

Delete Record

DELETE /api/record/:domain API key

DELETE /api/record/yourname
X-API-Key: YOUR_KEY

CLI — Install

The CLI is a single zero-dependency Python file. Python 3.8+ required.

# via pip
pip install ipn-fyi

# or grab the script directly
curl -O https://raw.githubusercontent.com/afterdarksys/ipn-cli/main/ipn.py
chmod +x ipn.py && sudo mv ipn.py /usr/local/bin/ipn

CLI — Commands

Command	Description
ipn register	Create a new account
ipn login [username]	Authenticate and save credentials
ipn configure	Set API key, host, or default domain
ipn whoami	Show current identity
ipn update	Update DNS record (auto-detects IP with --auto)
ipn records	List your DNS records
ipn history	Show IP change history
ipn delete <domain>	Delete a DNS record
ipn daemon	Background auto-update loop
ipn status	Show service and config health

CLI — Daemon Mode

Run ipn daemon to keep your IP current automatically:

# update every 5 minutes (default)
ipn daemon

# custom interval + include IPv6
ipn daemon --interval 60 --ipv6

# specific domain
ipn daemon --domain myserver

Examples — cURL

# register
curl -sX POST https://ipn.fyi/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'

# update IP (auto-detect with command substitution)
curl -sX POST https://ipn.fyi/api/update \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"domain\":\"alice\",\"ipv4\":\"$(curl -s https://api4.ipify.org)\"}"

# view records
curl -s https://ipn.fyi/api/records -H "X-API-Key: $API_KEY"

Examples — systemd

# /etc/systemd/system/ipn.service
[Unit]
Description=ipn.fyi Dynamic DNS updater
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=ipn daemon --interval 300
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

systemctl enable --now ipn

Examples — cron

# update every 5 minutes via cron
*/5 * * * * ipn update --auto >> /var/log/ipn.log 2>&1

# or with raw curl
*/5 * * * * curl -s "https://ipn.fyi/api/update?key=YOUR_KEY&domain=yourname&ipv4=$(curl -s https://api4.ipify.org)"