Skip to main content

Documentation 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.

Registering a domain is the first step in the custom domain lifecycle. This endpoint creates a new domain record, generates a cryptographically secure verification token, and returns the DNS instructions you need to prove ownership. Once you add the required TXT record to your DNS provider, you can call the verify endpoint to advance the domain to verified status.

​
Method and Path

POST /domains

​
Request Body

​
domain_name
string
required
The fully-qualified domain name you want to register, e.g. example.com. Must be unique — attempting to register a domain that already exists will return a database error due to the UNIQUE constraint on domain_name.

​
Response — 201 Created

​
id
string
Unique identifier for this domain record. Generated as a hex-encoded random 16-byte value (32 hex characters). Use this ID in all subsequent requests that reference this domain.
​
domain_name
string
The fully-qualified domain name that was registered, echoed back exactly as supplied.
​
verification_token
string
A cryptographically secure ownership token — the hex-encoded SHA-256 hash of 32 randomly generated bytes. This value must appear as a TXT record at _acme-challenge.<domain>. for ownership verification to succeed.
​
status
string
The current lifecycle status of the domain. Always pending immediately after creation. Possible values across the full lifecycle are pending, verified, certificate_pending, active, and failed.
​
instructions
string
A human-readable string describing exactly which DNS record to create, e.g. "Create a TXT record for _acme-challenge.example.com. with value: <token>". Add this record at your DNS provider before calling the verify endpoint.

​
Example

​
Request

curl -X POST http://localhost:8080/domains \
  -H "Content-Type: application/json" \
  -d '{"domain_name": "example.com"}'

​
Response

{
  "id": "3f2a1b4c5d6e7f8a9b0c1d2e3f4a5b6c",
  "domain_name": "example.com",
  "verification_token": "a3f1d2c4e5b6789012345678abcdef0123456789abcdef0123456789abcdef01",
  "status": "pending",
  "instructions": "Create a TXT record for _acme-challenge.example.com. with value: a3f1d2c4e5b6789012345678abcdef0123456789abcdef0123456789abcdef01"
}

​
Error Cases

StatusCause
400 Bad RequestThe request body is malformed JSON, or domain_name is missing or empty.
500 Internal Server ErrorA database error occurred — most commonly a UNIQUE constraint violation if the domain is already registered, or a storage failure.
Each domain name can only be registered once. The database enforces a UNIQUE constraint on domain_name, so a second POST /domains call with the same value will result in a 500 error. If you need to re-register a domain (e.g. after a failed verification), delete the existing record first.

Build docs developers (and LLMs) love

Get started for freeTalk to us