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 / Team and account

API keys and the API

The API lets a script, a deploy pipeline or a tool like Zapier, Make or n8n list, add, pause, resume and delete monitors, and receive events when something goes down. Every request needs your account's API key.

What you need first

  • You must be the account owner or a team admin. Editors and viewers see “The API key is managed by the account owner” instead of the key.
  • A way to send HTTPS requests, such as curl.

Find your key

  1. Open Settings and API.
  2. Find the API section. Your key is shown after “Key:” and starts with hw_.

Every account has one key. It belongs to the account, not to a person, so everyone who can see it sees the same key. Anyone with the key can see and change your monitors. Keep it out of public code and chat messages, and store it in your pipeline's secrets.

Make a new key

  1. Open Settings and API.
  2. In the API section, press Make a new key.
  3. Confirm when the browser asks. The new key shows straight away.

The old key stops working straight away. Update every script and tool that used it.

Send a test request

Send the key in the Authorization header. The base address is https://honkwatch.com/api/v1. This asks who the key belongs to and is the simplest test:

curl -H "Authorization: Bearer hw_..." https://honkwatch.com/api/v1/me

A working key answers with your account's id, email, name and plan, as JSON.

What you can do

GET /monitorsList your monitors with status, response time, uptime and expiry details.
GET /monitors/{id}One monitor.
POST /monitorsAdd a monitor. Send JSON with at least type and target.
POST /monitors/{id}/pausePause a monitor. Use /resume to start it again.
DELETE /monitors/{id}Delete a monitor and its history.
GET /hooks, POST /hooks, DELETE /hooks/{id}List, add and remove hooks. A hook sends events (down, up, slow, ssl or all) as JSON to an https address you choose.
GET /hooks/sample?event=downAn example event, so you can see the fields before a real one arrives.
GET /meCheck that a key works.

There is no API call to change an existing monitor. Change it in the app, or delete it and add it again. Monitors added through the API follow the same rules and plan limits as the form in the app.

Every field, with defaults and examples, is on the API reference page.

Add a monitor from a script

curl -X POST -H "Authorization: Bearer hw_..." -H "Content-Type: application/json" \
  -d '{"type":"http","target":"https://example.com","name":"Shop"}' \
  https://honkwatch.com/api/v1/monitors

A new monitor comes back with status 201 and its details, including its id. Keep the id if you want to pause or delete it later.

Limits

  • 60 requests a minute per key.
  • After 20 wrong keys from one address within 15 minutes, that address is refused for up to 15 minutes.
  • Up to 50 hooks per account. Hook addresses must start with https://.
  • Adding hooks needs a confirmed email address.

When it does not work

Errors come back as JSON with an error field that says what went wrong.

400The body is not valid JSON, or not a JSON object.
401“Bad API key”. The key is wrong, missing or was replaced by a new one. Check the header reads Authorization: Bearer, a space, then the key.
402The account has reached its monitor limit. See Plans and limits.
403For hooks: confirm your email address first. Otherwise the account is suspended; contact support.
404No monitor or hook with that id in this account.
422A field is missing or not accepted. The error says which, for example “A port check needs a port number.”
429Too many requests: wait a minute, or 15 minutes after many wrong keys. Also returned when the account already has 50 hooks.
← Plans and limits Your account →

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