---
title: "What public DNS shows for each record, and what is left to do"
method: GET
path: "/connections/{id}/diagnose"
tags: ["Connections"]
---

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

`GET /connections/{id}/diagnose`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/connections/{id}/diagnose`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.customdomain.ai/oauth/agent/authorize`, token URL `https://api.customdomain.ai/oauth/agent/token`, scopes: `domains:read`)

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

## Path parameters

- `id` string, required

## Response `200`

Diagnosis

- ConnectionDiagnosis
  - `connection_id` string, required
  - `domain` string, required
  - `zone` string, required: The DNS zone a panel manages (the registrable domain).
  - `provider` string
  - `status` 'pending' | 'propagating' | 'live' | 'failed', required
  - `checked_at` string, date-time
  - `all_found` boolean, required
  - `found_count` integer
  - `total` integer
  - `next_check_seconds` integer
  - `records` object[], required
    - `type` string
    - `host` string
    - `name` string: What to type in the Name/Host field ("@" for the root).
    - `value` string
    - `ttl` integer
    - `priority` integer
    - `status` 'found' | 'missing' | 'mismatch' | 'unverifiable'
    - `observed` string[]
    - `observed_label` string
    - `at_provider` boolean
  - `issues` object[], required
    - `code` 'doubled_host' | 'cloudflare_proxied' | 'aaaa_conflict' | 'extra_a_records' | 'conflicting_record' | 'caa_blocks'
    - `severity` 'blocking' | 'warning'
    - `name` string
    - `host` string
    - `observed` string[]
    - `message` string

## Other responses

- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: 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)