Quickstart

Create an account and API key

Sign up at dnsmint.com/login and create an API key in the dashboard. The key looks like dnsm_<keyId>_<secret> and the secret is shown once, at creation, so store it right away. An account can hold up to 20 keys, and you can revoke any of them from the dashboard at any time.

Register an IP

POST a public IPv4 or IPv6 address. The response is your new hostname, already resolving from our nameservers. New registrations may briefly return pending; poll GET until live.

$ curl -X POST https://dnsmint.com/api/v1/hostnames \
    -H "Authorization: Bearer $DNSMINT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ip": "34.120.50.10"}'

{
  "id": "68ad3a1e9c4b2f0d5e6a7b8c",
  "hostname": "q7k4m2.pool-3.mintzone.net",
  "ip": "34.120.50.10",
  "record_type": "A",
  "status": "live",
  "expires_at": "2026-09-02T08:30:00.000Z",
  "created_at": "2026-08-26T08:30:00.000Z"
}

Keep the id: every later call about this hostname uses it. IPv6 addresses work the same way and come back with record_type set to AAAA.

Point Caddy at the name

On the server behind that IP, put the hostname in your Caddyfile and start Caddy. It obtains a certificate from Let's Encrypt on its own, and the name serves HTTPS about a minute later.

q7k4m2.pool-3.mintzone.net {
    reverse_proxy localhost:3000
}

Any ACME client works the same way: certbot, Traefik, lego, and cert-manager can all issue for a DNSMint hostname over HTTP-01.

For wildcard certificates and machines on private networks, use the DNS-01 API: mint a scoped credential with POST /api/v1/hostnames/:id/acme-credential and hand the returned blob to any acme-dns-compatible client. Details in the API reference.

Update the IP when it changes

When the server moves, PUT the new address to the same id. The hostname and its certificate carry over untouched.

$ curl -X PUT https://dnsmint.com/api/v1/hostnames/68ad3a1e9c4b2f0d5e6a7b8c \
    -H "Authorization: Bearer $DNSMINT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ip": "34.120.51.22"}'

Renewal and lifecycle

Free hostnames live on a 7-day sliding idle expiry. Every authenticated touch of a hostname, whether reading it, updating its IP, or renewing it, moves expires_at to 7 days from that moment. A name your automation uses stays alive on its own; only a name idle for a full 7 days expires.

The explicit heartbeat is a POST with no body:

$ curl -X POST https://dnsmint.com/api/v1/hostnames/68ad3a1e9c4b2f0d5e6a7b8c/renew \
    -H "Authorization: Bearer $DNSMINT_KEY"

An expired name is not gone: its label stays reserved for your account, and a renew or IP update brings it back to live. Release is the permanent exit: DELETE the hostname and its label is retired forever, never reused by you or anyone else. That permanence is what keeps old certificates harmless.

Rate limits and caps

• Free accounts can hold 25 active hostnames. Registration past the cap returns a 429; release unused names or upgrade.
• An account can hold 20 API keys.
• Registration writes carry per-key rate limits. Reads, renewals, and DNS queries are unlimited on every plan; the fair use policy spells out exactly what that means.

Where to go next

The API reference documents all six endpoints with parameters, responses, and error codes. A machine-readable OpenAPI 3.1 description of the same API lives at /openapi.json.