set_url_check

PUT

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

curl --request PUT \
  --url https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/url-check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "body_match": { "mode": "contains", "pattern": "example" }, "body_max_bytes": 1, "credential": "example", "expected_status": { "kind": "two_xx" }, "follow_redirects": true, "json_extract": [ { "metric": "example", "path": "example" } ], "method": "GET", "timeout_ms": 1, "url": "example", "verify_tls": true }'

Authorizations

• bearer

Parameters

Path Parameters

node_id

required

string format: uuid

Node id

Request Body^required

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

Responses

204

URL check stored

400

The URL is malformed, not http(s), or points at a blocked address

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 ManageConfig

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

409

The node is already a monitor of another kind

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