Skip to content
HonkWatch
PricingLocationsHonk RadarHelpAPI Log inGet started
All help topics

Getting started

  • Getting started
  • How checks work

Monitors

  • Which monitor to use
  • Website monitor
  • API monitor
  • Keyword monitor
  • Ping monitor
  • Port monitors (TCP and UDP)
  • DNS monitor
  • SSL certificate monitor
  • Domain expiry monitor
  • Third-party services
  • Page load monitor
  • Heartbeat monitor (cron jobs)
  • Maintenance windows
  • Incidents

Alerts

  • Setting up alerts
  • Email alerts
  • Slack
  • Microsoft Teams
  • Discord
  • Telegram
  • PagerDuty
  • ntfy
  • Webhooks
  • Zapier

Phone and desktop app

  • The phone and desktop app
  • App alerts not arriving

Status pages

  • Status pages
  • Status page on your own domain

Team and account

  • Team members
  • Plans and limits
  • API keys and the API
  • Your account

Troubleshooting

  • A monitor says down but my site works
  • I did not get an alert
  • Allowing our checks through a firewall
  • Questions and answers

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

  1. Open Monitors and press Add monitor.
  2. Pick API (JSON reply).
  3. Type the address into API URL.
  4. 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.
  5. 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.
  6. 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}]
}
PathValue
statusok
db.connectedtrue
items.0.oktrue (the first item)
items.-1.okfalse (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 OK matches ok. For numbers, true, false and null, type them the way they appear in the JSON, for example true or 200.

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

  1. 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.
  2. 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.
  3. To check that the alert reaches you, open Alerts and press Send test next to a channel.

When it does not work

Reason shownWhat it means and what to do
HTTP 401 or HTTP 403The endpoint wants a key, or the key is wrong. Check the header under Request headers. Write it as Name: value, one per line.
HTTP 404The address is wrong. Copy it again from a request that works.
HTTP 405The endpoint does not accept that method. Change Method.
Reply is not JSONThe 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 objectThe 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.

← Website monitor Keyword monitor →

Still stuck? Email [email protected] and say which guide you were following.