---
title: "Start managed DNS for a connection's domain"
method: POST
path: "/connections/{id}/managed-dns"
tags: ["Managed DNS"]
---

# Start managed DNS for a connection's domain

`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

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

## Path parameters

- `id` string, required

## Request body

- object

## Response `200`

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

- ManagedDNSView
  - `zone` string, 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.
  - `nameservers` string[], required: The nameservers to set at the registrar.
  - `observed_nameservers` string[], required: The nameservers the registry listed at the last check.
  - `registrar` object, nullable, required: The domain's registrar from RDAP, or null when unknown.
    - `name` string, required
    - `url` string, required: The registrar's website, or an empty string.
  - `records` ManagedDNSRecord[], required
    - `id` string, required: Stable id derived from the record content.
    - `type` 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'SRV' | 'CAA' | 'NS', required
    - `name` string, required: Fully qualified owner name, lower case ("acme.com" is the apex, "*.acme.com" a wildcard).
    - `value` string, required: A/AAAA: the address. CNAME/NS/MX: the target host ("." for a null MX). TXT: the text. SRV: "<weight> <port> <target>". CAA: `<flags> <tag> "<value>"`.
    - `ttl` integer, required: Seconds.
    - `priority` integer, nullable, required: MX preference or SRV priority; null for other types.
    - `source` 'discovered' | 'imported' | 'customdomain' | 'manual', required: Where the record came from. `customdomain` records are the ones CustomDomain™ needs for connected domains; they win every conflict and can't be removed here.
  - `warnings` string[], required: Plain-language notes for the user (a partial delegation, records a zone file import skipped, records replaced).
  - `checked_at` string, date-time, required: When the delegation was last checked.
  - `activated_at` string, date-time, nullable, required

## Other responses

- `201`: The zone was created and filled.
- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `409`: The domain's zone is already hosted for another account, or another change to it is in progress.
- `422`: `managed_dns_unavailable` (this domain can't be hosted; `details` says why) or `managed_dns_limit` (the account's zone limit).
- `502`: `managed_dns_backend_error`: the DNS hosting service didn't respond. Nothing is lost; call again to finish.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)