API Documentation — ipdock.io

Authentication

ipdock.io uses two types of bearer tokens depending on what you're doing.

API Tokenpth_xxxxx

For DDNS updates. Per-hostname tokens created in the dashboard.

Authorization: Bearer pth_your_token_here

Used for: /api/update only

User JWTeyJhb...

For account management. Obtained via the login endpoint.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Used for: all other API endpoints

Quick Start — DDNS Update

This is what 90% of users need. Pick a method below and replace pth_your_token_here with your token from the dashboard.

Method 1Docker ClientRecommended

Set it and forget it. The container watches your IP and updates automatically.

docker run -d \
  --name ipdock \
  --restart=always \
  -e IPDOCK_TOKEN=pth_your_token_here \
  ipdockrepo/ipdock-client:latest

Method 2curl

# Auto-detect IP (uses your public IP)
curl -s https://api.ipdock.io/api/update \
  -H "Authorization: Bearer pth_your_token_here"

# Specify IP explicitly
curl -s "https://api.ipdock.io/api/update?ip=1.2.3.4" \
  -H "Authorization: Bearer pth_your_token_here"

# POST method
curl -s -X POST https://api.ipdock.io/api/update \
  -H "Authorization: Bearer pth_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"ip": "1.2.3.4"}'

Method 3DynDNS2 CompatibleRouters / NAS

Works with pfSense, OPNsense, Synology, UniFi, DD-WRT, OpenWrt, and any DynDNS2-compatible device.

URL:      https://api.ipdock.io/api/update?ip=<ipaddr>
Username: (leave blank or use "token")
Password: pth_your_token_here

Supported devices:
  - pfSense / OPNsense    → Dynamic DNS → Custom
  - Synology NAS          → Control Panel → External Access → DDNS → Customize
  - UniFi                 → Settings → Internet → Dynamic DNS
  - DD-WRT / OpenWrt      → any DynDNS2 provider slot

Method 4wgetfor minimal systems

wget -qO- "https://api.ipdock.io/api/update" \
  --header="Authorization: Bearer pth_your_token_here"

Method 5cron job

# Add to crontab (crontab -e) — update every 5 minutes
*/5 * * * * curl -s "https://api.ipdock.io/api/update" -H "Authorization: Bearer pth_your_token_here" > /dev/null 2>&1

Response Format

// Success — IP changed
{ "status": "good", "ip": "1.2.3.4", "previous": "5.6.7.8" }

// Success — IP unchanged
{ "status": "nochg", "ip": "1.2.3.4" }

// Error — invalid token
{ "error": "Invalid API token" }

Account Management API

POST/api/auth/register

Create a new account. Returns a JWT and user object.

curl -X POST https://api.ipdock.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

# Returns:
# { "token": "eyJhb...", "user": { "id": "...", "email": "...", "plan": "free" } }

POST/api/auth/login

curl -X POST https://api.ipdock.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

# Returns:
# { "token": "eyJhb...", "user": { "id": "...", "email": "...", "plan": "free" } }

Hostnames API

Hostnames are your DDNS entries (e.g. myserver.ipdock.io). Each hostname gets its own API token for updates.

GET/api/hostnames

List all hostnames for your account.

curl -s https://api.ipdock.io/api/hostnames \
  -H "Authorization: Bearer $JWT"

POST/api/hostnames

Create a new hostname. Returns the hostname object and a fresh API token.

curl -X POST https://api.ipdock.io/api/hostnames \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"domainId": "00000000-0000-0000-0000-000000000001", "name": "myserver", "ttl": 60}'

# Returns:
# { "hostname": {...}, "token": { "tokenValue": "pth_xxx..." } }

DELETE/api/hostnames/{id}

Delete a hostname and all its associated tokens.

curl -X DELETE https://api.ipdock.io/api/hostnames/{id} \
  -H "Authorization: Bearer $JWT"

Domains API

Bring your own domain. Delegate your domain's NS records to ipdock.io and get full zone management.

GET/api/domains

List all domains on your account (built-in and custom).

curl -s https://api.ipdock.io/api/domains \
  -H "Authorization: Bearer $JWT"

POST/api/domains

Add a custom domain. After adding, delegate NS records to ipdock.io, then verify.

curl -X POST https://api.ipdock.io/api/domains \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'

POST/api/domains/{id}/verify

Trigger an NS delegation check for a custom domain.

curl -X POST https://api.ipdock.io/api/domains/{id}/verify \
  -H "Authorization: Bearer $JWT"

GET/api/domains/{id}/delegation-status

Check the current NS delegation status of a domain.

curl -s https://api.ipdock.io/api/domains/{id}/delegation-status \
  -H "Authorization: Bearer $JWT"

DNS Records API

Self-Hoster+

Manage individual DNS records for your domains. A records are available on all plans. MX, SRV, CAA, and NS records require a Self-Hoster plan or higher.

GET/api/domains/{domainId}/records

List all DNS records for a domain.

curl -s https://api.ipdock.io/api/domains/{domainId}/records \
  -H "Authorization: Bearer $JWT"

POST/api/domains/{domainId}/records

Create a DNS record. Supported types: A, AAAA, CNAME, TXT, MX (Self-Hoster+), SRV (Self-Hoster+), CAA (Self-Hoster+), NS (Self-Hoster+).

# A record
curl -X POST https://api.ipdock.io/api/domains/{domainId}/records \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"type": "A", "name": "www", "content": "1.2.3.4", "ttl": 3600}'

# MX record (Self-Hoster plan or higher)
curl -X POST https://api.ipdock.io/api/domains/{domainId}/records \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"type": "MX", "name": "@", "content": "mail.example.com", "priority": 10, "ttl": 3600}'

# TXT record (SPF)
curl -X POST https://api.ipdock.io/api/domains/{domainId}/records \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"type": "TXT", "name": "@", "content": "v=spf1 include:_spf.google.com ~all", "ttl": 3600}'

PATCH/api/domains/{domainId}/records/{recordId}

Update an existing DNS record's content or TTL.

curl -X PATCH https://api.ipdock.io/api/domains/{domainId}/records/{recordId} \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "2.3.4.5", "ttl": 300}'

DELETE/api/domains/{domainId}/records/{recordId}

Delete a DNS record.

curl -X DELETE https://api.ipdock.io/api/domains/{domainId}/records/{recordId} \
  -H "Authorization: Bearer $JWT"

Tokens API

API tokens are scoped to individual hostnames. Each token can only update the hostname it was created for.

GET/api/tokens

List all API tokens for your account.

curl -s https://api.ipdock.io/api/tokens \
  -H "Authorization: Bearer $JWT"

POST/api/tokens

Create a new API token for a specific hostname.

curl -X POST https://api.ipdock.io/api/tokens \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"hostnameId": "...", "label": "my-server"}'

POST/api/tokens/{id}/regenerate

Regenerate a token (invalidates the old one). Useful if a token is compromised.

curl -X POST https://api.ipdock.io/api/tokens/{id}/regenerate \
  -H "Authorization: Bearer $JWT"

Rate Limits

EndpointLimitWindow

/api/update120 requestsper minute

/api/auth/login10 requestsper minute

/api/auth/register20 requestsper minute

All other endpointsStandardper minute

Rate limit headers are included in all responses: X-RateLimit-Remaining, X-RateLimit-Limit, Retry-After.

Error Handling

All errors return JSON with an error field and an appropriate HTTP status code.

401Unauthorized

{ "error": "Unauthorized" }

403Forbidden (plan limit)

{ "error": "MX records require a Self-Hoster plan or higher", "code": "PLAN_LIMIT", "upgrade": true }

404Not Found

{ "error": "Hostname not found" }

422Validation Error

{ "error": "A record content must be a valid IPv4 address" }

429Rate Limited

{ "error": "Too many requests" }

Router & Firewall Setup

Most routers and firewalls support Dynamic DNS via the DynDNS2 protocol or a custom URL. Use the update URL from your hostname token to keep your router's public IP in sync.

How it works

Your router calls the update URL. ipdock automatically detects the public IP from the incoming request — no need to specify it. Your DNS record is updated instantly.

https://api.ipdock.io/api/update?token=YOUR_TOKEN

🌐 UniFi (UDM / UDM Pro / Dream Router)

Works natively with UniFi's built-in Dynamic DNS. No extra software needed. Tested on UDM Pro Max running UniFi OS 4.x.

Go to Settings → Internet → WAN
Scroll to Dynamic DNS and click Create New Dynamic DNS
Set the fields:
Service: Dyndns
Hostname: your-host.ipdock.me (use your full FQDN)
Username: token
Password: pth_your_token_here
Server: api.ipdock.io/nic/update?hostname=%h&myip=%i
Click Save. UniFi will update your ipdock hostname automatically whenever your WAN IP changes.

The Server field path tells UniFi exactly how to format the update request.%h is substituted with your hostname and %i with your current WAN IP.

🔥 pfSense

Go to Services → Dynamic DNS
Click + Add to create a new entry
Set the fields:
Service Type: Custom
Interface: WAN
Update URL: https://api.ipdock.io/api/update?token=YOUR_TOKEN
Result Match: "status":"good" or "status":"nochg"
Description: ipdock DDNS
Set Check IP Services to your preferred method and Save & Force Update

ipdock detects your IP automatically from the request. The result match string confirms a successful update.

🛡️ OPNsense

Go to Services → Dynamic DNS
Click + to add a new account
Set the fields:
Service: Custom
Username: token
Password: YOUR_TOKEN
Hostname: your-host.ipdock.me
Check ip method: Interface
Interface: WAN
Update URL: https://api.ipdock.io/api/update?token=YOUR_TOKEN
Enable the entry and click Save. Test with Force Update.

💻 cURL / Cron

For Linux servers, a simple cron job works:

# Add to crontab -e (runs every 5 minutes)
*/5 * * * * curl -s "https://api.ipdock.io/api/update?token=YOUR_TOKEN"

Ready to get started?

Create a free account and have your first hostname running in minutes.

Create Free Account Go to Dashboard