Help

NepBox writes your current public IP into your subdomain through a single HTTP endpoint. Below are the endpoint parameters, its response codes, typical cron jobs and troubleshooting tips.

Quick start

  1. Sign in with Google; the account starts with 2 points of quota.
  2. Create a subdomain in the console and add A / AAAA records as needed.
  3. Copy the update URL from the subdomain details and hand it to your router or a scheduled job.

Update endpoint

GET https://api.nepbox.com/update
Parameter Required Description
domain yes Subdomain, without .nepbox.com
token yes Update token of that subdomain; can be reset from the console
ip no Set an IPv4 address explicitly, written to the A record
ipv6 no Set an IPv6 address explicitly, written to the AAAA record

When neither ip nor ipv6 is given, the endpoint looks at the address the request came from: IPv4 updates the A record, IPv6 updates the AAAA record. If the address has not changed the endpoint answers ok and performs no write at all.

Examples

# Auto-detect the source IP
curl -4 "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN"
curl -6 "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN"

# Set the address explicitly
curl "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN&ip=1.2.3.4"
curl "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN&ipv6=2001:db8::1"

Response codes

Body HTTP Meaning
ok 200 Success. Also returned when the address has not changed
badparam 400 domain / token missing, or a malformed address
noip 400 No address was provided and none could be derived from the request
badtoken 403 Malformed token, or a token that does not belong to this subdomain
toomanyrequests 429 Rate limit exceeded: 20 requests per minute per source IP, shared by all subdomains on it
toomanychanges 429 This subdomain used up its address changes for today (50 per day); Retry-After points at the next reset
error 500 Server or Cloudflare error, retry later

* The rate limit counts requests, while the 50-per-day cap counts updates that actually change an address: polling with an unchanged address counts towards neither (it is only subject to the per-minute request limit). One request that updates both IPv4 and IPv6 counts as one change.

Scheduled jobs

Linux / NAS (crontab, every 5 minutes):

*/5 * * * * curl -4 -s "https://api.nepbox.com/update?domain=YOUR_DOMAIN&token=YOUR_TOKEN" > /dev/null

Telegram change notifications

Once Telegram is linked, the bot sends you a message whenever a subdomain address changes: the domain, record type, the old and new addresses, the source and the time.

  1. Sign in with Google and open the profile page;
  2. Click “Link Telegram” — the page generates a one-time link valid for 10 minutes;
  3. Tap “Start” in Telegram; once you see “binding successful” it is done, notifications are on by default.

Records added, edited or deleted by hand in the console notify you too; the “source” line distinguishes DDNS 自动更新 (automatic DDNS update) from 控制台手动修改 (manual console edit).

To take a break:

* Notifications are only a convenience channel: even if a message fails to deliver (for example you blocked the bot), DDNS updates keep working.

Troubleshooting

The address is not updating

  1. First check that the endpoint answers ok;
  2. Verify the record: nslookup YOUR_DOMAIN.nepbox.com, keeping TTL and local DNS caching in mind;
  3. If you edited the record manually in the Cloudflare dashboard, the old value stored on the server makes the endpoint believe there is nothing to update — edit the record once in the console;
  4. Make sure the device uses the current token: after a token reset the old update URL stops working immediately.

Why is there only one A and one AAAA record per subdomain?

This service is focused on DDNS: every subdomain has an apex only and keeps a single record per type, which the update endpoint overwrites. If you need more record types or hostnames, create a separate subdomain for each purpose.

Why must a subdomain be at least 5 characters?

Shorter names are scarce and easy to squat or abuse, hence the 5 character minimum. Each subdomain costs 1 point of quota, and deleting it returns the point.

What if the token leaks?

Click “Reset token” in the subdomain details: the old token stops working immediately, then update the URL stored on your devices.

Why are only 20 change entries kept?

DDNS clients poll frequently; to keep the database from growing without bound, each subdomain keeps its latest 20 change entries and older ones are deleted automatically.

Anything else?

Email support@nepbox.com.