get_dns_chain

GET

/api/v1/nodes/{node_id}/dns-chain

curl --request GET \
  --url https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/dns-chain \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Responses

200

The node’s current resolution chain and how long it has held

Media typeapplication/json

The node’s current resolution chain, plus how long it has held.

object

chain

required

One observed resolution chain — the artifact of a DNS check.

Produced by the transport, carried on PollResult.dns_chain, persisted to PostgreSQL. Never a TSDB label (ADR-011); it is the same tier as the interface inventory and sys_descr.

object

failure

One of:

null

null

object

One of:

object

Authoritative “no such name” (RCODE 3).

object

kind

required

string

Allowed values: nx_domain

object

NOERROR, but no record of the requested type and no CNAME to follow.

object

kind

required

string

Allowed values: no_data

object

The resolver failed to answer the question (RCODE 2).

object

kind

required

string

Allowed values: serv_fail

object

The resolver refused to answer (RCODE 5).

object

kind

required

string

Allowed values: refused

object

Any other response code, kept numeric so a new RCODE is never lost.

object

kind

required

string

Allowed values: other_rcode

rcode

required

The raw DNS response code.

integer format: int32

object

The resolver did not answer within the check’s budget.

object

kind

required

string

Allowed values: timeout

object

A CNAME pointed at a name already visited in this chain.

object

at

required

The name the loop closed on.

string

kind

required

string

Allowed values: loop_detected

object

The chain was longer than the configured max_depth.

object

kind

required

string

Allowed values: depth_exceeded

max_depth

required

The limit that was hit.

integer format: int32

object

The response could not be decoded or did not match the question asked.

object

kind

required

string

Allowed values: malformed

hops

required

The hops in walk order. Order is significant and is never sorted.

Array<object>

One hop of a resolution chain: the name asked about and the answers that came back for it.

object

answers

required

The answers whose owner is name, canonicalized (sorted, deduped, capped).

Array<object>

One answer record plus its TTL.

The TTL is display-only: it counts down between polls, so including it in the content key would make every single poll register as a change.

object

record

required

One of:

object

A CNAME alias target (normalized: lowercase, no trailing dot).

object

kind

required

string

Allowed values: cname

target

required

The name this hop is an alias for.

string

object

An IPv4 address record.

object

addr

required

The resolved IPv4 address.

string

kind

required

string

Allowed values: a

object

An IPv6 address record.

object

addr

required

The resolved IPv6 address.

string

kind

required

string

Allowed values: aaaa

ttl

required

Time-to-live as reported by the resolver, in seconds.

integer format: int32

name

required

The name queried at this hop (normalized).

string

query

required

The name originally asked for (normalized).

string

record_type

required

The record type asked for.

string

Allowed values: A AAAA CNAME

resolve_ms

required

Total wall-clock milliseconds for the walk. Not part of the content key.

number format: double

resolver

required

Where we asked, rendered for display (e.g. 10.0.0.53:53 or system). Provenance, not content: swapping resolvers while the answer stays the same is not a change.

string

failure_kind

One of:

null

null

string

Why a resolution failed, without the detail that distinguishes one instance from another — the failure_kind column, and what the API serves for grouping.

string

Allowed values: nx_domain no_data serv_fail refused other_rcode timeout loop_detected depth_exceeded malformed

first_seen

required

string

last_seen

required

string

resolved

required

boolean

Example

{
  "chain": {
    "failure": {
      "kind": "nx_domain"
    },
    "hops": [
      {
        "answers": [
          {
            "record": {
              "kind": "cname"
            }
          }
        ]
      }
    ],
    "record_type": "A"
  },
  "failure_kind": "nx_domain"
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks View

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

No resolution has been recorded for the node

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Inventory storage is unavailable (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}