DNS Handling exposes a JSON REST API over HTTP for managing custom domain verification and automated TLS certificate issuance via ACME DNS-01 challenges. All endpoints accept and returnDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/plutoploy/dns-handling/llms.txt
Use this file to discover all available pages before exploring further.
application/json. The API is intentionally minimal — it models a linear domain lifecycle from registration through DNS verification to certificate issuance, with each stage gated on the previous one completing successfully.
Base URL
The server binds to:8080 by default, making the base URL:
SERVER_ADDR environment variable before starting the service:
Authentication
This service has no authentication layer. It is designed to run as an internal component, not exposed to the public internet.Content-Type
All requests that include a body must set theContent-Type header to application/json. All responses are JSON regardless of status code.
Request IDs
The chi router applies themiddleware.RequestID middleware to every request. Each response carries an X-Request-Id header that can be used to correlate log entries with API calls.
Error Format
All error responses share a consistent JSON envelope with a singleerror field and an appropriate HTTP status code.
| Status Code | Meaning |
|---|---|
400 Bad Request | Invalid request body or a precondition not met (e.g. domain not yet verified) |
404 Not Found | Domain or certificate does not exist |
424 Failed Dependency | DNS lookup failed when attempting verification |
500 Internal Server Error | Unexpected server-side failure |
Endpoints
The API is organised around two resources — Domains and Certificates — all nested under the/domains prefix.
| Method | Path | Description |
|---|---|---|
POST | /domains | Register a new domain and obtain a verification token |
GET | /domains/{id} | Retrieve current domain status |
POST | /domains/{id}/verify | Trigger DNS TXT record verification |
POST | /domains/{id}/issue-certificate | Start ACME DNS-01 certificate issuance |
GET | /domains/{id}/certificate | Retrieve certificate metadata |
Domains
Register domains, check verification status, and trigger DNS TXT record verification. A domain must reach
verified status before certificate issuance can begin.Certificates
Initiate ACME DNS-01 certificate orders and retrieve certificate metadata once issuance completes asynchronously in the background.
Domain Status Lifecycle
Every domain moves through a well-defined set of statuses. Transitions are strictly ordered — no step can be skipped.| Status | Description |
|---|---|
pending | Domain has been registered; DNS TXT record not yet verified |
verified | DNS TXT record confirmed; domain is eligible for certificate issuance |
certificate_pending | ACME DNS-01 order has been started; polling for TXT record propagation |
active | Certificate successfully issued and stored |
failed | ACME polling timed out or the certificate order could not be completed |
Certificate PEM and private key PEM are stored in the database after a successful ACME order but are not returned by any API endpoint.
GET /domains/{id}/certificate exposes metadata only — id, domain_id, issued_at, expires_at, and created_at. Retrieve the raw PEM material directly from the database if needed.