API documentation

The API is deliberately small. Create a base hostname without an account, then use its secret token to manage it.

Management tokens are sent using Authorization: Bearer YOUR_TOKEN. Do not place tokens in query strings.

Create a hostname

GET https://api.instantdns.io/new

Creates a new base hostname and points it at the IP address making the request.

$ curl https://api.instantdns.io/new

The returned token is shown once. Save it somewhere safe.

Authentication

TOKEN='your-secret-token'

curl \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/record/list

A token controls one base hostname and its child records.

Update the base hostname

GET /update

Updates only the base hostname to the IP address making the request.

curl \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/update

To update the parent and every active child record:

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/update?scope=all"

scope	Behaviour
`parent`	Updates the base hostname only. This is the default.
`all`	Updates the base hostname and every active child record.

Create a child record

GET /record/new?name=camera1

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/new?name=camera1"

If your parent hostname is orange-oak-3294.instantdns.io, this creates:

camera1.orange-oak-3294.instantdns.io

Update one child

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/update?name=camera1"

A disabled child is automatically reactivated when it is updated.

List records

curl \
  -H "Authorization: Bearer $TOKEN" \
  https://api.instantdns.io/record/list

The response includes the base hostname, its current IPv4 and IPv6 addresses, and every child record with its active state.

Disable a child

curl \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.instantdns.io/record/delete?name=camera1"

This is intentionally reversible. The DNS record is removed, but its metadata is retained. Calling /record/update later reactivates it.

IPv4 and IPv6

InstantDNS detects the address family used to reach the API. An IPv4 request updates the A record; an IPv6 request updates the AAAA record. The other address family is preserved.

# Force IPv4
curl -4 https://api.instantdns.io/new

# Force IPv6
curl -6 https://api.instantdns.io/new

Rate limits

Rate limits exist to keep the free service usable and discourage bulk namespace harvesting.

Action	Limits
New base hostnames	3/minute, 10/5 minutes, 30/hour
Child creation	10/minute, 30/5 minutes, 100/hour
IPv6 protection	Addresses are grouped by network prefix for abuse control.

A rate-limited request returns HTTP 429 and includes fields such as:

{
  "error": "rate_limit_exceeded",
  "limit_type": "per_minute",
  "retry_after_seconds": 42,
  "limit": 3,
  "window_seconds": 60
}

API status

$ curl https://api.instantdns.io/

{"service":"InstantDNS","status":"ok"}