Configuration

Configuration

Create a rule under Setup → Agents → Other integrations → Generic JSON API (ruleset special_agents:json_api).

A rule holds one or more endpoints. Each endpoint is fetched independently and all their results merge into one agent section, so a single rule can monitor several related APIs on the same host.

Endpoint settings

Field	Purpose
URL	Full endpoint URL incl. scheme, e.g. https://app.example.com/actuator/health. Checkmk macros ($HOSTNAME$, $HOSTADDRESS$, custom host macros, …) are resolved against the monitored host, so one rule can be shared across many hosts.
HTTP method	GET or POST.
Request body	Optional body for POST (defaults Content-Type: application/json unless you set one). Macros are resolved here too.
Additional request headers	Name/value pairs; macros are resolved in the values.
Authentication	None, HTTP basic (username/password), or bearer token. Secrets go through the password store — never in clear text on the command line.
Verify the TLS certificate	On by default. Turning it off is insecure and opt-in.
Follow HTTP redirects	On by default; turn it off to harden against redirect-based SSRF (see Security).
Request timeout (seconds)	Optional; defaults to 30.
Fields to monitor	One entry per service (below).

Fields to monitor

Each field turns one JSON value into one service.

Field	Purpose
Service name	Becomes the service, shown as JSON <name>.
JSON path	Dotted path to the value; use [*] for array discovery. See JSON paths.
Item label path	For [*] paths: the field within each element used to label the discovered service (defaults to the array index).
Unit	Optional: count / bytes / seconds / percent — renders the metric/graph with that unit (numeric values only).
Upper / lower levels	WARN/CRIT thresholds for numeric values.
Expected value (regex)	The value must fully match this regex, else CRIT.

Service names must be unique across the whole rule. If two endpoints produce the same name, the later one is auto-suffixed with (2) — but explicit, distinct names read better.

How a value becomes a service state

Situation	Result
Numeric value with levels	Checked against the levels; emitted as a metric (named for the unit, or json_api_value).
Value with an expected regex	OK if it fully matches, else CRIT.
Plain value, no levels/regex	Shown in the summary (numeric values still get a metric).
Levels set on a non-numeric value	WARN — so the misconfiguration is visible.
Path not found	UNKNOWN.
Endpoint request failed / not JSON	That endpoint's services go UNKNOWN with the error; other endpoints keep reporting.

Values are rendered as they appear in JSON, so an expected regex matches true / false / null — not Python's True / False / None.

Where a value came from

The service Details view shows the JSON path, the source endpoint URL, and the expected pattern (when set). This makes a wrong-path or wrong-endpoint extraction easy to spot. It's details-only — it never changes the summary line or the service state.

Applying the rule

After saving: activate changes, then run service discovery on the target host. The new JSON … services appear and can be added to monitoring.

---

Next: JSON paths · Examples.