The Custom Domains API

Add a custom domain to your platform with one API call. The request below creates a domain connection. From there, Custom Domain configures DNS, verifies ownership, and issues TLS without another line of code from you. The request and response shapes on this page are illustrative; the authoritative reference, with every endpoint, parameter, and error code, is at app.customdomain.ai/docs.

curl -X POST https://api.customdomain.ai/v1/connections \ -H "Authorization: Bearer $CUSTOM_DOMAIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "domain": "shop.acme.com", "target": "edge.yourplatform.com" }'

A successful call returns the connection along with its verification challenge:

{ "id": "con_01j9x4", "domain": "shop.acme.com", "status": "pending", "verification": { "method": "dns_txt", "record": { "type": "TXT", "name": "_cd-challenge.shop.acme.com", "value": "cd-verify=7f3a9b" } }, "tls": { "status": "awaiting_verification" }, "created_at": "2026-07-15T14:03:00Z" }

The connection then moves from pending to verified to live. When your customer's DNS provider supports one-click provider authorization, or the customer supplies an API token, the whole sequence completes in about 30 seconds. When it does not, the API returns the exact records for a guided manual flow, and verification still completes automatically the moment those records resolve.

One API for programmatic custom domains

Custom Domain runs as a control plane plus a reverse-proxy edge that terminates TLS for every connected domain, with strict isolation between tenants. The REST API is the front door to that control plane, and it covers seven surfaces:

• Connections: create, inspect, and remove customer domains.
• DNS records: read the records behind each connection and what still needs to change.
• Verification: prove domain ownership before any traffic is served.
• TLS: track issuance and renewal for every certificate.
• Monitoring: health and drift checks on live domains.
• Webhooks: push every state change into your systems.
• Registrar: search for and purchase domains inside your own flow.

If you would rather not write integration code at all, the embeddable widget and SDK wrap this same API. See features and how it works for the full picture, or follow the walkthrough in add custom domains to your SaaS.

The domain connection API

Connections are the core resource. A connection maps a domain your customer owns, say shop.acme.com, to a target on your platform. You create one with POST /v1/connections, list them with GET /v1/connections, fetch one with GET /v1/connections/:id, and remove one with DELETE. Each connection carries its complete state, covering DNS, verification, and TLS, so a single GET tells you exactly where a customer's domain stands and what, if anything, is blocking it.

Connections are scoped per tenant. One customer can never see, claim, or interfere with another customer's domain, which matters when thousands of tenants share the same edge. If you are still weighing build versus buy, custom domains for SaaS lays out what a production integration actually involves.

DNS records without support tickets

Most platforms lose customers at the DNS step, so the records API is designed to remove it. Custom Domain integrates with 63 DNS and registrar providers. For most customers, records are written automatically, either through one-click provider authorization where the provider supports it or through an API token the customer supplies once. For everyone else, the API returns the exact records to create and keeps checking until they resolve.

GET /v1/connections/:id/records returns both what should exist and what currently exists, so you can render precise, provider-aware instructions in your own UI instead of pointing customers at a generic help article. Whether a customer should connect an apex domain or a subdomain is its own question; apex domain vs CNAME covers the tradeoffs.

The domain verification API

No traffic is served and no certificate is issued until ownership is proven. The domain verification API issues a challenge for each connection, typically a TXT record like the one in the response above, then checks for it continuously. Once the challenge resolves, the connection is marked verified and the rest of the pipeline proceeds on its own. Your customer never hands over nameservers and never grants more access than the verification requires.

Verification state is queryable at any time via GET /v1/connections/:id, and every transition is pushed to your webhook endpoint, so your dashboard can show "verifying" and "connected" states in real time without polling. For background on the ownership model, see bring your own domain.

TLS lifecycle, from issuance to renewal

The moment a connection verifies, the edge requests a certificate for it, and renewal is scheduled automatically from then on. Certificates terminate at the edge, so you never generate a CSR, never store a private key, and never wake up to an expired certificate on a customer's domain.

GET /v1/connections/:id/tls reports the certificate's status, issuer, and renewal window, which is useful for compliance reviews and customer support. If you want to understand the machinery, automate TLS for customer domains walks through the lifecycle, multi-tenant TLS explains how certificates for thousands of unrelated domains coexist safely, and on-demand TLS covers issuing certificates the first time a domain is seen.

Monitoring and webhooks

Live domains drift. Customers migrate providers, delete records they do not recognize, or let registrations lapse. The monitoring endpoints report per-connection health, and webhooks push changes as they happen, so you find out before your customer's visitors do.

{ "event": "connection.live", "data": { "connection_id": "con_01j9x4", "domain": "shop.acme.com", "tls": { "status": "issued", "renews_at": "2026-09-13" } } }

Register an endpoint with POST /v1/webhooks and subscribe to the events you care about: connection created, verified, and live, TLS issued and renewed, and drift detected. Event names above are illustrative; the current catalog is in the docs.

Registrar search and purchase

Some customers arrive without a domain at all. The registrar endpoints let them search availability and complete a purchase inside your product, and the new domain connects itself, since Custom Domain controls its DNS from the first second.

curl "https://api.customdomain.ai/v1/registrar/search?q=acme+coffee" \ -H "Authorization: Bearer $CUSTOM_DOMAIN_TOKEN"

This turns "add a custom domain via API" into a single onboarding step: search, buy, live, with no detour to a registrar's website and no DNS work afterward. It is a natural fit for site builders and ecommerce platforms, where a domain is part of the product's first-run experience.

The MCP server for AI agents

Everything above is also exposed through a hosted MCP server at https://mcp.customdomain.ai/mcp, so AI agents can search for a domain, purchase it, connect it, and watch verification complete, with the same ownership gates a human would pass through. An agent building a site for a client can take that site live on the client's own domain without a person touching DNS.

If your product is an agent, or your customers work through one, see Custom Domain for AI agents and the guide to connecting domains with AI agents.

Start with the free tier

The custom domains API, the widget, the webhooks, and the MCP server are all available from the free tier; pricing starts at $0 and scales with connected domains. Create an API token at app.customdomain.ai/signup, keep the docs open beside your terminal, and your first domain connection can be live before your coffee cools. If you would rather talk through your architecture first, book a demo.