Help / Monitors
API monitor
An API monitor calls an address that answers with JSON. It checks the status code, checks that the reply really is JSON, and can check that one value in the reply is what you expect, such as "status": "ok".
What you need first
- The full address of the endpoint, for example
https://api.example.com/health. It must be reachable from the public internet. - If the endpoint needs a key or token, the header that carries it. A read-only key is best: it is stored with the monitor and sent with every check.
- An example of the reply, so you can find the path to the value you want to check.
Set it up
- Open Monitors and press Add monitor.
- Pick API (JSON reply).
- Type the address into API URL.
- Under Check the reply, fill in Value at (dotted path, optional) and Must equal (optional) if you want to check a value. Both are explained below.
- If the endpoint needs headers, a different method or a body, open More settings and fill in Method, Request headers, one per line and Request body.
- Give it a Friendly name, choose Check every and press Start monitoring.
Writing the path
The path says where the value is in the reply. Separate names with dots. Use a number for a place in a list, counting from 0. A path may start with $., which is ignored.
Say the endpoint replies with this:
{
"status": "ok",
"db": {"connected": true},
"items": [{"ok": true}, {"ok": false}]
}
| Path | Value |
|---|---|
status | ok |
db.connected | true |
items.0.ok | true (the first item) |
items.-1.ok | false (the last item) |
What counts as a pass
- No path: a good status code and a reply that is valid JSON.
- A path, no "Must equal": as above, and the value must exist.
- A path and "Must equal": the value must match what you typed. Capitals do not matter, so
OKmatchesok. For numbers,true,falseandnull, type them the way they appear in the JSON, for exampletrueor200.
The good status codes are set under More settings and are 200-399 unless you change them. We send Accept: application/json with each request unless you set your own Accept header.
Until you confirm your email address, checks can only use GET or HEAD without a request body.
Test it
- Before saving, open the address in your browser or with a tool such as curl, and confirm the path leads to the value you expect.
- After saving, the monitor page shows "Working" once the first checks pass. Each city in the location list shows its last answer, with the reason if it failed. When the monitor goes down, the reason is also shown under the status.
- To check that the alert reaches you, open Alerts and press Send test next to a channel.
When it does not work
| Reason shown | What it means and what to do |
|---|---|
| HTTP 401 or HTTP 403 | The endpoint wants a key, or the key is wrong. Check the header under Request headers. Write it as Name: value, one per line. |
| HTTP 404 | The address is wrong. Copy it again from a request that works. |
| HTTP 405 | The endpoint does not accept that method. Change Method. |
| Reply is not JSON | The reply is an HTML page, empty, or cut short. We read up to 512 KB of the reply, so a larger reply cannot be read whole. Point the monitor at a smaller endpoint, such as a health check. |
| No value at ... | The path does not lead to anything. Check spelling and capitals in the names, and that list numbers start at 0. |
status is a different text (5 characters), expected ok, or a different number, list or object | The value exists but does not match Must equal. The reason does not repeat the value itself, because reasons can appear on status pages and in alerts. Look at the reply yourself to see what it says. |
For timeouts, blocked checks and other problems shared with website monitors, see Website monitor. If it says down but the endpoint works for you, see A monitor says down but my site works.
Still stuck? Email [email protected] and say which guide you were following.