list_dns_chain_history

GET

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

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

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Query Parameters

limit

integer format: int64

before_at

string

before_id

integer format: int64

Responses

200

One page of chain changes, newest first

Media typeapplication/json

One page of chain changes, newest first.

object

changes

required

Array<object>

One append-on-change history row.

object

at

required

string

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

id

required

integer format: int64

prev_chain_key

string | null

resolved

required

boolean

next

One of:

null

null

object

Pass back as before_at+before_id for the next page; null ⇒ this was the last one.

object

at

required

string

id

required

integer format: int64

Example

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

400

Before_at and before_id must be given together, and before_at must be RFC 3339

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"
  }
}

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"
  }
}

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"
  }
}