Quickstart

Get an API key

Sign up at dnsmint.com/login and create an API key in the dashboard. The key looks like dnsm_<key_id>_<secret> and the secret is shown once, at creation, so store it right away. You can revoke any key from the dashboard at any time.

A key does not have to reach your whole account. The Limit to field narrows one to a single domain or a single hostname, which is what belongs on a deploy box, or on the machine that renews one certificate and should not be able to touch the rest. The API reference sets out every scope.

Register an IP

POST an address, IPv4 or IPv6, public or private. What comes back is your hostname, already resolving from our nameservers. Only ip is required. Give a subdomain of 3 to 63 lowercase letters, digits and hyphens with no period, or omit it and we mint an opaque one; name a domain you already hold, or omit it and we pick one of yours.

$ 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", "subdomain": "api", "domain": "dnsmint-7b2e04.dev"}'

{
  "id": "68ad3a1e9c4b2f0d5e6a7b8c",
  "hostname": "api.dnsmint-7b2e04.dev",
  "status": "pending",
  "certificate": "self",
  "created_at": "2026-08-26T08:30:00.000Z"
}

A new registration comes back pending and is live a moment later; poll GET for the change. Keep the id: every later call about this hostname uses it. The response does not repeat the address back at you, because DNS answers that authoritatively and a copy here could only disagree with the zone; ask /v1/hostnames/{id}/diagnose for what we are actually serving.

Serve HTTPS

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 hostname serves HTTPS about a minute later.

api.dnsmint-7b2e04.dev {
    reverse_proxy localhost:3000
}

Any ACME client works the same way over HTTP-01. The integrations page has a recipe for certbot, acme.sh, lego, Traefik, cert-manager and Posh-ACME.

For wildcard certificates, and for machines on private networks, use the DNS-01 API. Mint a DNS-01 credential with POST /api/v1/hostnames/:id/acme-credential and hand the returned blob to any acme-dns-compatible client. The protocol is 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. If the address has not changed, a PUT is a no-op: there is no keepalive to send, and a hostname stays live without being touched.

$ 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"}'

Release a hostname

A hostname stays until you release it. DELETE stops the record at once and revokes any certificate we hold for it. The subdomain returns to your account and can be minted again straight away, since nobody else is on your domain. The released hostname itself stays released: writes to it return 409, and minting the subdomain again creates a new hostname with a new id.

Rate limits and caps

• Starter accounts can hold 5 active hostnames. Registration past the cap returns a 429; release unused hostnames or upgrade.
• Registration writes and updates carry technical rate limits, listed in the API reference. Reads and DNS queries are unlimited on every plan; the fair use policy spells out exactly what that means.

Or hand it to an agent

Everything above is curl, and an agent can run it. Put your API key in DNSMINT_API_KEY and paste this.

Give this runtime a public HTTPS hostname using DNSMint. Read https://dnsmint.com/llms-full.txt for the full API, register this runtime's public IP, and set up Caddy to serve HTTPS on the hostname it returns. My API key is in the DNSMINT_API_KEY environment variable.

It works from /llms-full.txt, which is this API written for a model to read rather than a person.

Where to go next

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