Summary
Add a custom domain on Starter or Pro and return SPF, DKIM, DMARC, and MX records plus a verify TXT. GET /api/v1/domains lists them. GET /api/v1/domains/:id shows status (pending until DNS matches, then verified), mail, status_detail, and warnings. Each record includes status (valid, missing, or invalid), found from the last check, and hint. hint is null when the record is valid or no specific mistake was found. Otherwise hint is {code, message, found_at} and says what to change. warnings is an empty array when none. existing_mail_provider means this hostname already has MX at another provider, and the message suggests a subdomain such as agents.example.com. Which records are valid, missing, or invalid is unchanged. The same domain or client_id returns the original row. Cooper writes the records only when that hostname is already in a Cloudflare zone on the operator account, and never registers a domain or creates a zone. The daily cron GET /api/v1/internal/digests/flush checks DNS and sends domain.verified. Free returns HTTP 402 plan_limit_exceeded with upgrade_url. When usage is at 80 percent of a plan limit, the response includes notices. {{domainMailNotice}}
Request
{
"domain": "agents.example.com",
"client_id": "zone-1"
}Response
The OpenAPI document does not declare a JSON response schema for this call. The summary is the contract.Errors
- HTTP 402 plan_limit_exceeded
Idempotency
client_id makes this write idempotent. Sending the same client_id again returns the original object instead of creating a duplicate.