# DNSMint: full reference This file is the complete DNSMint reference in one document, written for machine ingestion. The human version lives at https://dnsmint.com/docs and the OpenAPI 3.1 spec at https://dnsmint.com/openapi.json. ## What DNSMint is DNSMint is a hostname registration service: an authenticated API call registers an IP address and returns a stable hostname on a domain DNSMint operates, served by DNSMint's authoritative DNS. The hostname is an opaque label that does not encode the IP, stays the same when the registered IP changes, and works with any ACME client, so Caddy or certbot can get a free certificate for it. DNSMint never proxies or carries customer traffic; connections go straight from clients to the registered server. ## Authentication Every API request needs an API key in the Authorization header: Authorization: Bearer dnsm__ Keys are created in the dashboard at https://dnsmint.com/dashboard. The secret is shown once, at creation, and stored only as a hash after that. An account can hold up to 20 keys, and keys can be revoked from the dashboard at any time. A missing, malformed, or revoked key returns 401: { "error": "Missing or invalid API key", "code": "UNAUTHORIZED" } ## API Base URL: https://dnsmint.com/api/v1. Requests and responses are JSON. Request bodies are capped at 4KB. A hostname object looks like this in every response that returns one: { "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" } Fields: id (opaque identifier used in URLs), hostname (fully qualified name), ip (the registered address), record_type ("A" for IPv4 or "AAAA" for IPv6, following the address), status ("pending", "live", "expired", or "released"), expires_at and created_at (ISO 8601 timestamps). New registrations may briefly return "pending"; poll GET until "live". ### POST /v1/hostnames (create) Registers a public IP and mints a new hostname. Optional body field "label" picks a custom label (Pro/Business). Returns 201. 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" } Errors: 400 (bad JSON, missing "ip", invalid address, invalid or blocked label, body over 4KB), 401, 403 (private IP, or custom label without Pro), 409 (custom label taken or retired), 429 (account already has 25 active hostnames), 500. ### GET /v1/hostnames (list) Lists the account's hostnames, newest first, excluding released ones. Expired names appear with status "expired". Listing renews nothing. Query parameters: limit (default 100, clamped to 1..500) and skip (default 0), for pagination. curl "https://dnsmint.com/api/v1/hostnames?limit=100&skip=0" \ -H "Authorization: Bearer $DNSMINT_KEY" { "hostnames": [ { "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" } ] } Errors: 401, 500. ### GET /v1/hostnames/{id} (read one) Returns one hostname. Reading a live hostname counts as use and slides its expiry to 7 days from now. A hostname already marked expired is returned as expired; revive it with the renew endpoint. New registrations may briefly return "pending"; poll GET until "live". curl https://dnsmint.com/api/v1/hostnames/68ad3a1e9c4b2f0d5e6a7b8c \ -H "Authorization: Bearer $DNSMINT_KEY" Response: 200 with the hostname object. Errors: 401, 404 (no hostname with this id on this account), 500. ### PUT /v1/hostnames/{id} (update the IP) Points the hostname at a new public IP. The name and any certificates issued for it are unchanged. The record type follows the new address, so a name can move between A and AAAA. The name comes back live with expiry 7 days out, even if it had expired. Body: {"ip": ""}. 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"}' Response: 200 with the updated hostname object. Errors: 400, 401, 403 (private or reserved IP), 404, 409 (the hostname was released), 500. ### POST /v1/hostnames/{id}/renew (renew) Heartbeat with no request body. Slides the idle expiry to 7 days from now and brings an expired (but not released) hostname back to live. curl -X POST https://dnsmint.com/api/v1/hostnames/68ad3a1e9c4b2f0d5e6a7b8c/renew \ -H "Authorization: Bearer $DNSMINT_KEY" Response: 200 with the renewed hostname object (status "live", new expires_at). Errors: 401, 404, 409 (the hostname was released), 500. ### DELETE /v1/hostnames/{id} (release) Releases the hostname permanently. The DNS record stops being served and the label is never reused, by this account or any other. Releasing an already released hostname returns the same success response. curl -X DELETE https://dnsmint.com/api/v1/hostnames/68ad3a1e9c4b2f0d5e6a7b8c \ -H "Authorization: Bearer $DNSMINT_KEY" { "released": true } Errors: 401, 404, 500. ## Lifecycle rules - A hostname starts live with a 7-day idle expiry. New registrations may briefly return "pending"; poll GET until "live". - Every authenticated use of a specific hostname slides expires_at to 7 days from that moment: creating it, reading it by id, updating its IP, or calling renew. Listing the collection does not renew anything. - A name idle for a full 7 days expires: the record stops being served and status reads "expired". - An expired name is recoverable. Its label stays reserved for the owning account, and a renew or IP update brings it back to live. - Release (DELETE) is permanent. A released label is never reused by any account, which keeps certificates issued for it harmless. Attempts to update or renew a released name return 409. ## IP rules - Public IPv4 and IPv6 addresses are accepted today. IPv4 gets an A record, IPv6 an AAAA record. - Private and reserved addresses (RFC 1918 ranges, loopback, link-local, CGNAT, multicast, IPv6 ULA and v4-mapped forms) are rejected with 403. Private-IP registration is a Business plan feature and is coming; it is not available yet. ## Error codes Every non-2xx response is { "error": "", "code": "" }. | Status | Code | When | |--------|----------------|-------------------------------------------------------------------| | 400 | BAD_REQUEST | Bad JSON, missing "ip", invalid address, or body over 4KB | | 401 | UNAUTHORIZED | Missing or malformed Authorization header, unknown or revoked key | | 403 | FORBIDDEN | The IP is in a private or reserved range | | 404 | NOT_FOUND | No hostname with this id belongs to the account | | 409 | CONFLICT | The hostname was released and cannot change | | 429 | RATE_LIMITED | The account is at its 25 active-hostname cap | | 500 | INTERNAL_ERROR | Unexpected server error | ## Serving HTTPS with Caddy On the server behind the registered IP, put the minted hostname in a 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: certbot, Traefik, lego, and cert-manager can all issue for a DNSMint hostname over HTTP-01. ## DNS-01 certificate API (acme-dns compatible) For wildcard certificates and machines on private networks. Credentials are scoped to one hostname each. Mint a credential (API-key auth; the password appears once; max 5 per hostname): curl -X POST https://dnsmint.com/api/v1/hostnames/HOST_ID/acme-credential \ -H "Authorization: Bearer $DNSMINT_KEY" Response (the acme-dns registration blob clients persist): { "username": "2f1e6a9c-8b3d-4e5f-9a1b-6c7d8e9f0a1b", "password": "f3a9...", "fulldomain": "_acme-challenge.q7k4m2.pool-1.example", "subdomain": "2f1e6a9c-8b3d-4e5f-9a1b-6c7d8e9f0a1b", "server_url": "https://dnsmint.com/api/acme", "allowfrom": [] } Publish a challenge (the acme-dns wire protocol; certbot, Caddy, Traefik, lego, and cert-manager speak it unmodified): curl -X POST https://dnsmint.com/api/acme/update \ -H "X-Api-User: " -H "X-Api-Key: " \ -d '{"subdomain": "", "txt": "<43-char challenge>"}' Response: {"txt": "<43-char challenge>"}. The two newest values per name are served (covers apex plus wildcard double validation). subdomain must equal the credential's username. Credentials for released or expired hostnames stop working. Errors: 401 invalid credentials, 403 subdomain mismatch, 400 malformed txt. ## CAA records Pool domains can publish CAA so a chosen CA is the only one allowed to issue for names on that domain. Admin-only: PATCH /api/admin/domains/:id with {"caa": ["0 issue \"letsencrypt.org\""]} (flags 0-255, tag issue / issuewild / iodef, value quoted). An empty array clears the records. Names without CAA still return empty NOERROR (any CA may issue). ## Pricing Billing is month to month; cancel any time. DNS queries, API reads, and renewals are unlimited on every plan. | Plan | Price | What you get | |----------|---------------|----------------------------------------------------------------------| | Free | $0 | 25 active hostnames on a shared domain pool, public IPv4 and IPv6, names renew on use and expire after 7 idle days | | Pro | $9.99 / month | Your own dedicated domain, custom labels, names stay for the life of the subscription | | Business | $29.99 / month| 5 dedicated domains, private IP ranges, scoped tokens and team seats, SLA | Pricing page: https://dnsmint.com/pricing ## Fair use summary Unlimited means DNS queries, API reads, and renewals are never metered, billed, or throttled for legitimate workloads, however heavy. The fair use policy exists for attacks and platform abuse only: denial of service against the nameservers, using the API as a storage or exfiltration channel, evading rate limits across accounts, and hosting phishing or malware. Hard limits that do exist: registration writes carry per-key rate limits (burst plus sustained), and each tier has a published cap on active hostnames (25 on Free) with no hidden quotas. Enforcement follows a ladder: automated mitigation, then notice, then suspension; phishing and malware hostnames are taken down immediately. Full policy: https://dnsmint.com/fair-use. Report abuse: abuse@dnsmint.com. ## FAQ Q: How fast is a new hostname usable? A: Seconds for DNS, about a minute for HTTPS. The API reports the record as live once every nameserver answers for it, and Let's Encrypt usually finishes right after. Q: What happens when my server's IP changes? A: Send one PUT with the new address. The hostname and its certificate carry over untouched, so everything pointing at the name keeps working. Q: Who sees my traffic? A: You and your users. DNSMint's role ends at the DNS answer; connections run directly to your server, on your bandwidth, with your TLS keys. Q: Which certificate authorities work? A: Any ACME certificate authority. Let's Encrypt, Google Trust Services, ZeroSSL, and Buypass all issue free certificates for DNSMint hostnames, and your private keys stay on your server. Q: How long do free names last? A: As long as you keep using them. Every authenticated touch renews a free name for another week; a name idle for a full week retires. Retired labels are permanently retired, which keeps any certificate issued for them harmless. Paid names stay for the life of the subscription. Q: What do I need to bring? A: A server with an IP your users can reach. The domain, the DNS, and the certificate plumbing are included. On paid plans your names live on a domain dedicated to you, with Let's Encrypt rate limits all to yourself. ## Links - Site: https://dnsmint.com - Quickstart: https://dnsmint.com/docs - API reference: https://dnsmint.com/docs/api - OpenAPI spec: https://dnsmint.com/openapi.json - Pricing: https://dnsmint.com/pricing - Fair use: https://dnsmint.com/fair-use - Questions: https://dnsmint.com/questions - Contact: hello@dnsmint.com - Report abuse: abuse@dnsmint.com