get_url_check

GET

/api/v1/nodes/{node_id}/url-check

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

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Responses

200

The node’s URL-check configuration

Media typeapplication/json

A node’s URL-monitoring configuration (1:1 with the node). No secrets: the optional auth credential is a reference; core resolves/inlines the decrypted value (ADR-018/020).

object

body_match

One of:

null

null

object

Optional keyword rule applied to the response body.

object

mode

Whether the keyword must be present or absent (default: present).

string

Allowed values: contains not_contains

pattern

required

The keyword to look for. Matched as plain, case-sensitive text — not a regular expression.

string

body_max_bytes

How many bytes of the response body to read (default 65536, range 1024–1048576). Applies to both body_match and json_extract; the body is not read at all unless one of them is set.

integer format: int32

credential

One of:

null

null

string

Optional auth credential (Basic/Bearer/custom header). A reference only — core resolves it to an [HttpAuth] and inlines that into the poll job, the same path SNMP credentials take.

string format: uuid

expected_status

One of:

object

Any 2xx (the default).

object

kind

required

string

Allowed values: two_xx

object

An explicit set of acceptable codes.

object

codes

required

Array<integer>

kind

required

string

Allowed values: exact

object

An inclusive range [lo, hi].

object

hi

required

integer format: int32

kind

required

string

Allowed values: range

lo

required

integer format: int32

follow_redirects

Follow 3xx redirects (default true).

boolean

json_extract

Values to lift out of a JSON response body and record as operator-named metrics.

Each rule adds one gauge per poll. A rule whose path is missing, or whose value is not a number, records nothing for that poll rather than a zero.

Array<object>

One number to lift out of a JSON response body and record as a metric.

object

metric

required

The metric name to record the value under, e.g. queue_depth. Must match [A-Za-z_:][A-Za-z0-9_:]* and must not be one of the names the monitor already emits.

string

path

required

Dot-separated path to the value, e.g. data.queue.depth or items.0.value. Array elements are indexed by number; items[0].value is accepted and means the same thing.

Not a JSONPath expression: the path names exactly one location, so the rule always produces either one number or nothing.

string

method

Request method (default GET).

string

Allowed values: GET HEAD POST

timeout_ms

Per-request timeout, in milliseconds (default 5000).

integer format: int32

url

required

Full URL to probe, e.g. https://api.example.com/health.

string

verify_tls

Verify the TLS certificate chain (default true; never silently disabled — security.md).

boolean

Example

{
  "body_match": {
    "mode": "contains"
  },
  "expected_status": {
    "kind": "two_xx"
  },
  "method": "GET"
}

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

The node carries no URL check

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