---
title: "Why a hostname is not working"
method: GET
path: "/v1/hostnames/{id}/diagnose"
---

# Why a hostname is not working

`GET /v1/hostnames/{id}/diagnose`

## Request

- Base URL: `https://dnsmint.com/api`
- URL: `https://dnsmint.com/api/v1/hostnames/{id}/diagnose`
- Auth: HTTP bearer

Runs the checks we can run from the authoritative side and returns a verdict for each, with the next action on anything that failed.

Read-only. Nothing here writes a record, re-signs a zone or orders a certificate, so it is safe to call on a schedule and safe to retry.

Always 200 when the hostname exists, including when every check fails - that is the case this endpoint is for, so the verdict is in the body rather than the status code. Each check carries `verdict`: `pass`, `fail`, `warn`, `unknown` (we could not find out, which is never the same as fine) or `skipped` (an earlier answer made it meaningless). `summary` names the first failure, because it is usually the cause of the ones after it.

## Path parameters

- `id` string, required

## Response `200`

The diagnosis

- Diagnosis
  - `hostname` string
  - `summary` string: The first failure, or a statement that the hostname is working.
  - `checks` DiagnosticCheck[]
    - `id` 'status' | 'record' | 'address' | 'delegation' | 'nameservers' | 'public' | 'dnssec' | 'caa' | 'challenge' | 'certificate'
    - `label` string
    - `verdict` 'pass' | 'fail' | 'warn' | 'unknown' | 'skipped': unknown means we could not find out, which is never the same as pass.
    - `detail` string: What we saw.
    - `action` string: What to do about it. Absent on pass.
  - `checked_at` string, date-time
  - `checkedAt` string, date-time: Deprecated spelling, still accepted. Use `checked_at`.

## Other responses

- `401`: Missing or invalid API key
- `403`: Key lacks hostnames:read, or is narrowed to another hostname
- `404`: Hostname not found
- `429`: Too many diagnoses for this account

---

[API](https://skmtc.dev/dnsmint/apis/dnsmint-api.md) · [All operations](https://skmtc.dev/dnsmint/apis/dnsmint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dnsmint/apis/dnsmint-api/revisions/98fb1f87725a?raw)