APIs are the plumbing of modern software. If your UK business integrates with payment providers, CRM platforms, email services, logistics APIs, financial-data providers, or publishes its own product API for customers, you have a stack of endpoints that matter as much as your website. An HTTP(s) monitor can confirm that the endpoint responds. What it cannot confirm is that the response means what you expect. The JSON Query monitor fills that gap — it fetches a JSON endpoint, evaluates a JSONPath expression against the response, and asserts that the value matches what you know to be healthy. This guide walks through how to use it effectively for UK production APIs. If you are new to Uptime Kuma, our plain-English introduction is the right starting point.
Why API health checks need their own monitor
An API's HTTP status code is often a poor indicator of whether the API is actually working. Three common cases:
API returns 200 with an error payload. Well-designed REST APIs return HTTP status codes that match real semantics — 200 for success, 4xx for client errors, 5xx for server errors. Less well-designed APIs return 200 with {"status": "error", "message": "..."} in the body and expect the caller to parse. An HTTP(s) monitor sees 200 and declares success. A JSON Query monitor reads the status field and correctly flags failure.
API returns 200 with stale data. A caching layer in front of the API returns a cached response long after the origin has started failing. The status code is fine; the data is wrong. Asserting on a freshness field (a timestamp, a counter, a last-updated field) catches this.
Health-check endpoint reports degraded state. Many modern APIs expose a structured health endpoint that returns {"status": "ok", "dependencies": {...}}. You want to monitor whether the API considers itself healthy, including dependencies — an HTTP(s) monitor only sees the status code from the health endpoint itself, not the nuance inside.
JSON Query monitors replace status-code-only monitoring on API endpoints with assertion-based monitoring on the structured response. For the broader context on how detection speed maps to business impact, see our true cost of downtime for UK businesses.
There is also a subtler reason to separate API monitoring from web monitoring: APIs and web pages fail in different ways and at different times. A deploy that updates the front-end only might leave the API unchanged; a database issue that affects reads but not writes shows up first on query-heavy API endpoints; a third-party dependency failure surfaces at the integration layer long before it reaches the rendered page. Monitoring each layer with the right tool gives you diagnostic clarity that a single blended approach does not.
JSON Query vs plain HTTP(s)
The JSON Query monitor is essentially the HTTP(s) monitor with two extra fields — a JSONPath expression and an expected value — and an automatic JSON parse of the response. Everything else carries over: authentication, request method (GET, POST, PUT, PATCH), custom headers, request body, timeouts, retries, SSL certificate verification.
The configuration form adds:
- JSON Path: the JSONPath expression that selects the value to check against.
- Expected Value: the string the selected value should equal.
If the selected value equals the expected value, the monitor is up. If the selected path does not exist in the response, or the value does not match, the monitor is down. If the response is not valid JSON, the monitor is down. If the HTTP request fails for transport reasons (connection refused, timeout, TLS error), the monitor is down — all the HTTP-level failure modes still apply.
For straightforward cases — an endpoint that returns {"status": "ok"} on success — the JSONPath is $.status and the Expected Value is ok. That covers a substantial majority of simple API health checks.
JSONPath in one page
JSONPath is the query language used to navigate JSON documents. It is to JSON what XPath is to XML. You do not need the whole specification, but a working vocabulary of half a dozen expressions covers almost every production use case.
| Expression | Meaning | Example document | Result |
|---|---|---|---|
$ | Root of the document | {"a": 1} | The whole document |
$.status | Top-level field named "status" | {"status": "ok"} | "ok" |
$.health.api | Nested field | {"health": {"api": "up"}} | "up" |
$.items[0].id | First element of array | {"items": [{"id": 42}]} | 42 |
$.items.length | Array length (in some implementations) | {"items": [1,2,3]} | 3 |
$..version | Recursive search for "version" anywhere | {"a": {"version": "2.0"}} | "2.0" |
Uptime Kuma's JSONPath implementation supports the common subset. Recursive descent ($..), filters and slices work; some of the more exotic JSONPath extensions from specific libraries may not. When in doubt, test with a simple expression first and build up.
The Expected Value field is a simple string compare against the stringified result of the JSONPath evaluation. For numeric fields, the comparison still works because Uptime Kuma coerces both sides to strings — just be aware that 42 will match "42" in the expected field but not "42.0".
Common health-check patterns
Most APIs expose one of a few common health-check shapes. Here is how to monitor each.
Simple status field. Endpoint returns {"status": "ok"}. JSONPath $.status, expected ok. Monitors flip down the moment the status changes to anything else.
Boolean healthy flag. Endpoint returns {"healthy": true}. JSONPath $.healthy, expected true. String comparison still works — true matches "true".
Nested dependency status. Endpoint returns {"api": "ok", "database": "ok", "cache": "ok"}. Configure one monitor per dependency: $.api, $.database, $.cache, each with expected ok. You then know immediately which dependency fell over, not just that something failed.
Version assertion. Endpoint returns {"version": "2.3.1"}. Useful during deploys — the monitor is up only when the deployed version equals the expected one. Detects rollbacks or missed deploys.
Counter threshold (manual). Uptime Kuma does not support numeric comparisons natively (greater-than, less-than), but you can use recursive descent plus an expected value to assert on steady-state conditions. For anything more sophisticated, Prometheus is the right tool — Uptime Kuma is deliberately simple.
Array-element presence. Endpoint returns {"errors": []}. JSONPath $.errors.length, expected 0. Flags the moment the errors array gains any entries.
Boolean combined check. Some health endpoints combine multiple sub-checks into a single boolean — {"all_ok": true, "database": true, "cache": true}. Asserting on $.all_ok equalling true catches compound failures in one monitor, although you lose the granularity of which sub-system failed. A pragmatic pattern is one monitor on the composite flag for alerting, plus monitors on each sub-component for diagnostics — the alert fires from the composite, but the sub-component monitors tell you which piece went wrong.
Last-updated freshness. For data pipelines, assert on the latest import timestamp being recent. Uptime Kuma cannot compare times directly, but if the API exposes a status like {"last_import": "today"} or {"freshness": "fresh"}, the monitor can assert against those categorical values. For precise time-based thresholds, pair it with a cron-like Push monitor from the pipeline itself.
Authentication headers
Most production APIs require authentication. Uptime Kuma's JSON Query monitor handles the common patterns.
Bearer token. Add {"Authorization": "Bearer YOUR_TOKEN"} to Request Headers. Rotate the token in Uptime Kuma when you rotate it at the API. For tokens that expire on a short cycle (OAuth 2.0 access tokens), the Authentication Method field offers native OAuth 2.0 Client Credentials support, where Uptime Kuma exchanges client ID and secret for a fresh token on each run.
API key in custom header. Many UK APIs — particularly payment providers and some of the government-published APIs — use a specific header name. Add it as Request Headers, for example {"X-API-Key": "abc123"}.
Basic authentication. Select Basic from the Authentication Method dropdown and supply username and password. Appropriate for internal APIs behind reverse-proxy-layer Basic auth.
mTLS. For enterprise APIs requiring mutual TLS, supply a client certificate and key via the mTLS option. The files live on the Uptime Kuma host.
One practical consideration: API keys rotated at the API need to be rotated at the monitor. A stale key produces HTTP 401/403 on every check and the monitor reports persistent failure. Some UK teams schedule a quarterly reminder to audit monitor credentials; others use short-lived OAuth tokens to sidestep the issue. A sensible hygiene pattern is to keep the list of API keys used in monitors in the same place you keep other credential records, so that credential rotation automatically triggers a review of the monitors depending on them.
Another pattern worth mentioning: where possible, use a monitor-specific credential rather than the same key your production code uses. If the monitor's key is compromised (for example, if someone exports the Uptime Kuma database and rifles through it), the blast radius is limited to whatever the monitor was able to see — typically a read-only health endpoint — rather than exposing full API access.
A managed Uptime Kuma plan on smartxhosting.uk gives you a fresh Uptime Kuma instance on UK infrastructure. You log in, create the admin account and configure JSON Query monitors against any API endpoint — your own, partner APIs, SaaS dependencies — with whatever authentication scheme the endpoint requires. The application is the standard Uptime Kuma release; platform management sits with the provider.
Handling rate limits
APIs that publish a public health endpoint sometimes rate-limit the same endpoint that you want to monitor. If Uptime Kuma's polling interval exceeds the API's rate limit, checks start returning HTTP 429 and the monitor reports failure even though the API is fine.
Three ways to handle this.
Raise the interval. If the API allows 60 requests per hour from an unauthenticated client, a 60-second interval is too aggressive. 5 minutes is safer. For most public APIs, monitoring every few minutes is sufficient signal.
Authenticate. Authenticated clients typically get much higher rate limits. Supplying an API key (even a free-tier one) often removes the rate-limit concern entirely.
Use a dedicated health endpoint. Many APIs publish a /health or /status endpoint that is exempt from general rate limits and is specifically intended for monitoring. Check the API documentation; if one exists, use it instead of monitoring the main API endpoints directly.
If rate limits are fundamentally an issue — for example because you want aggressive 30-second monitoring against an API that will not allow it — accept that keyword-matching an HTML page, or configuring 429 as an accepted status code, may be the realistic answer. For broader keyword monitoring patterns on web pages, see our HTTP(s) monitoring guide.
Asserting on response-time fields
Some modern APIs include their own performance metrics in the response — for example {"status": "ok", "latency_ms": 87}. Uptime Kuma cannot do numeric comparisons directly, but there are two workable patterns.
Fixed-value assertion. If the health endpoint returns "latency_category": "fast" or similar categorical value, a JSON Query monitor can assert on that. When the category drops to "degraded" the monitor flips.
Composite monitoring. Use Uptime Kuma's own response-time recording on the HTTP(s) or JSON Query monitor — displayed in the monitor's history chart — as the performance signal. It is not as precise as application metrics, but it is accurate enough to spot trends.
For true performance monitoring with thresholds, percentiles and alerts on specific latency measurements, complement Uptime Kuma with Prometheus and Alertmanager or a commercial APM tool. Uptime Kuma's strength is availability monitoring; performance monitoring is an adjacent problem.
A note on timeouts for JSON Query monitors specifically: APIs that take a long time to respond (for example, because they trigger expensive backend computation) need generous timeouts. The default 48-second timeout is enough for almost any well-designed health endpoint, but a JSON Query monitor pointed at a general API endpoint that does real work can hit the timeout if the API is even moderately loaded. Tighten the timeout only on dedicated health endpoints where a long response itself is a signal of trouble.
Also worth noting: if the API you are monitoring returns different JSON shapes depending on a query parameter, make sure your JSONPath expression is valid for the shape you are fetching. A JSONPath that assumes an array can silently become invalid when the API starts returning a single object. Uptime Kuma will report the monitor as down with a "path not found" error, but the error detail is the only thing that tells you the shape changed — reading those details when a monitor flips is part of good operational hygiene.
Real-world UK SaaS examples
Three composite setups we have seen working well in UK production.
Example 1: UK e-commerce + payment provider. An HTTP(s) monitor on the shop homepage; a keyword monitor on the checkout page; a JSON Query monitor on the payment provider's status API ($.status, expected operational). If the payment provider goes down, the shop team knows immediately — before customers start emailing "payment failed".
Example 2: B2B SaaS with microservices. One JSON Query monitor per internal service health endpoint. Each monitor asserts on its own $.status. Plus one umbrella monitor on the public status-page API asserting that $.overall equals ok. When one internal service degrades, the specific monitor flips; the umbrella monitor reflects the compound status.
Example 3: Analytics SaaS with data freshness. A JSON Query monitor against /api/health asserting $.status is ok, plus a second monitor against /api/latest-import asserting that $.status is succeeded. Catches the case where the web service is fine but the nightly data import has failed — a silent problem that HTTP-only monitoring misses entirely.
Example 4: UK logistics integration. A SaaS that integrates with several UK courier APIs (Royal Mail, DPD, Hermes) configures one JSON Query monitor per courier against its official status API. When a courier's API goes down, the support team sees it in Uptime Kuma before customers start emailing about failed shipments. The monitors pay for themselves the first time a courier has a wobble.
Example 5: GOV.UK platform APIs. Public-sector projects integrating with .gov.uk platform APIs (notify, pay, verify) have long monitored those endpoints because they are not operated by the consuming service. A JSON Query monitor against the relevant health endpoint, with the appropriate service-credentials authentication, catches outages in platform services before the main service integration logs them.
Example 6: Graph database readiness. Some UK SaaS businesses now run graph databases (Neo4j, TigerGraph) alongside relational stores. A JSON Query monitor against a readiness endpoint that reports {"graph_ready": true} catches the case where the graph layer has fallen behind or failed to start — a condition that often does not manifest on the relational side until much later.
Common thread: you configure monitors against the specific signals that reflect what you actually care about. For routing the alerts into an inbox or team channel, see our SMTP notifications guide.
Summary
JSON Query monitors are the right tool for monitoring APIs. They go beyond "did the server respond" to "did the server return the right answer" — which for anything serving structured data is the real question. The learning curve is modest: a working knowledge of half a dozen JSONPath expressions, familiarity with the authentication patterns your APIs use, and awareness of rate limits is enough to cover virtually every UK production scenario.
Start with $.status against any health endpoint you already have. Extend to nested dependency status fields, version assertions and freshness checks as your monitoring matures. Use it in combination with HTTP(s) and keyword monitoring to cover web layer, content layer and API layer each with the right tool.