# Start managed DNS for a connection's domain

> Start managed DNS for a connection's domain: CustomDomain™ API reference in the managed dns group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/managed-dns/startManagedDNS

## `POST https://api.customdomain.ai/v1/connections/{id}/managed-dns`

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

The end user's widget token (scope `connect`) can start it only when the application offers DNS hosting on CustomDomain™: its `nameserver_migration` setting has mode `offer` or `prefer` and target `managed`. With the setting off the call answers 403 `forbidden` with the details "this application does not offer nameserver migration"; with target `dns_host` or `custom` it answers 403 `forbidden` with "this application hosts its users' DNS elsewhere; the nameserver move is its offer". Either way no zone is created. A connection that already has a zone can still call it, to resume. API keys and app-scoped tokens are not limited by the setting, and reading or editing an existing zone's records is unchanged. `managed_dns` on `POST /v1/domains:check` stays the deployment's and the domain's verdict; it does not say whether the application offers hosting.

The end user's widget token acts only on what is its own. A connection that names an end user (`end_user_ref`) is the token's when that is the token's own `end_user_ref` (mint the token with it); a connection that names none (an API key made it) is the token's only when its domain is one the token is bound to. A token with an `end_user_ref` and no bound domain owns none of those, and a token with no `end_user_ref` and no bound domain counts only this connection's domain. The call's connection must be the token's: a connection of another end user answers 403 `token_wrong_end_user` before anything is created or linked (the create call refuses a token for that end user's exact name too, so it is not handed that connection's id). One zone serves the whole registrable domain, so a zone that already exists is started, joined or resumed only when every connection linked to it is the token's too. Another end user's zone, one that also holds another name's connection of the platform (made with an API key) or a connection of another application, and one nobody is linked to (the end user removed its last connection; the platform's API key starts it for the new one) answer 409 `conflict`, "the DNS of acme.com is already hosted by CustomDomain™ for someone else"; nothing is linked or written and the answer shows none of the zone. A zone this call creates is the caller's. Two starts at once by one end user on a new zone can answer one of them 409; the same call again succeeds. API keys and app-scoped tokens are not limited by it.

### Authentication

`apiKey`, `widgetJWT`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Responses

| Status | Description |
| --- | --- |
| `200` | Managed DNS was already started; the zone as it stands. |
| `201` | The zone was created and filled. |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | `forbidden` (the application does not offer DNS hosting on CustomDomain™, or a role that cannot write connections), `token_wrong_end_user` (a widget token: the connection belongs to another end user; mint a token with this domain's `end_user_ref`), or `workspace_suspended` (see the `ForbiddenOrSuspended` response). |
| `404` | Error envelope: {code, title, details}. |
| `409` | The domain's zone is already hosted for another account, or (for a widget token) for someone else: not every connection linked to it is the token's (another end user's, the platform's for another name, another application's), or none is linked. 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}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `zone` | string | yes | The hosted zone: the registrable domain. |
| `status` | `awaiting_delegation`, `active`, `failed` | yes | `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` | array of string | yes | The nameservers to set at the registrar. |
| `observed_nameservers` | array of string | yes | The nameservers the registry listed at the last check. |
| `registrar` | object | yes | The domain's registrar, or null when unknown. |
| `records` | array of object | yes |  |
| `warnings` | array of string | yes | Plain-language notes for the user (a partial delegation, records a zone file import skipped, records replaced). |
| `checked_at` | string | yes | When the delegation was last checked. |
| `activated_at` | string or null | yes |  |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.
