# What public DNS shows for each record, and what is left to do

> What public DNS shows for each record, and what is left to do: CustomDomain™ API reference. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/connections/diagnoseConnection

## `GET https://api.customdomain.ai/v1/connections/{id}/diagnose`

Read-only, record-by-record check of a connection against live public DNS. For each record in the desired set it reports `found`, `missing`, `mismatch` (something else answers for the name; `observed` shows what, `observed_label` names a well-known service behind it) or `unverifiable`, plus the `name` to type in a DNS panel (`@` for the root) and `at_provider` when the domain's own nameservers already serve the value and only public caches lag. `issues` lists problems that block the connection even when a record looks right: `doubled_host` (the full hostname typed into the Name field), `cloudflare_proxied`, `aaaa_conflict`, `extra_a_records`, `conflicting_record` and `caa_blocks`. It never changes the connection; when `all_found` is true, call `:recheck` to verify and go live. Cached for about 5 seconds.

A delegated agent token needs `domains:read`.

A widget token must be the connection's end user: a connection that names another end user than the token's `end_user_ref`, or names one while the token names none, answers `403` `token_wrong_end_user` before anything is read or changed, and a connection that names none is any token's. An API key, an app-scoped token and a delegated agent token are not limited by it.

### Authentication

`widgetJWT`, `apiKey`, `agentToken`

### Parameters

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

### Responses

| Status | Description |
| --- | --- |
| `200` | Diagnosis |
| `401` | Error envelope: {code, title, details}. |
| `403` | `forbidden`: the credential may not do this. `token_wrong_end_user`: a widget token that is not this connection's end user (the connection names another end user than the token's `end_user_ref`, or names one while the token names none); nothing is read or changed, and the answer shows nothing of the connection. Mint the token with the end user's `end_user_ref`. |
| `404` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | yes |  |
| `domain` | string | yes |  |
| `zone` | string | yes | The DNS zone a panel manages (the registrable domain). |
| `provider` | string | no |  |
| `status` | `pending`, `propagating`, `live`, `failed` | yes |  |
| `checked_at` | string | no |  |
| `all_found` | boolean | yes |  |
| `found_count` | integer | no |  |
| `total` | integer | no |  |
| `next_check_seconds` | integer | no |  |
| `records` | array of object | yes |  |
| `issues` | array of object | yes |  |

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