Start managed DNS for a connection's domain

Offers the connection's end user a one-time change instead of typing records: point the domain's nameservers at CustomDomain™, and we host the zone and write every record from then on.

The first call creates a hosted zone for the connection's REGISTRABLE domain (acme.com, also for shop.acme.com), copies the records the domain already serves at common names (apex A/AAAA/MX/TXT/CAA, www, mail hosts, DMARC, common DKIM selectors, common SRV names, and every name the connection needs) so nothing breaks at the switch, adds the records CustomDomain™ needs for the connection, looks up the registrar, and answers 201 with the zone. Later calls answer 200 with the same zone; nothing is created twice. A second connection under the same registrable domain joins the existing zone. The zone becomes active once every nameserver the registry lists for the domain is ours; the connection then verifies and goes live on its own.

Available only when managed_dns.available is true on POST /v1/domains:check (the deployment flag is on, and the domain's nameservers can be changed at a registrar). Authorized like the other connection routes: an API key within the tenant, or a widget token of the connection's own application (and domain, when the token is bound to one).

post/connections/{id}/managed-dns

Request

Base URL: https://api.customdomain.ai/v1
URL: https://api.customdomain.ai/v1/connections/{id}/managed-dns
Auth: one of:
- HTTP bearer
- HTTP bearer

Path parameters

idstring required

Request body

object required

Response

Managed DNS was already started; the zone as it stands.

zonestring required

The hosted zone: the registrable domain.

status'awaiting_delegation' | 'active' | 'failed' required

awaiting_delegation: the zone holds the records; set the nameservers below at the registrar. active: every nameserver the registry lists is ours. failed: the switch never happened within 14 days, or the nameservers moved away again (the first warning says which); a failed zone keeps being checked and turns active once the delegation appears.

nameserversstring[] required

The nameservers to set at the registrar.

observed_nameserversstring[] required

The nameservers the registry listed at the last check.

warningsstring[] required

Plain-language notes for the user (a partial delegation, records a zone file import skipped, records replaced).

checked_atstring date-time required

When the delegation was last checked.

activated_atstring date-time nullable required

Example response

{
  "zone": "acme.com",
  "records": [
    {
      "id": "mdr_1f3a9c0b7d2e5a4c6b8d"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.