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
- Open Settings and API.
- 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
- Open Settings and API.
- In the API section, press Make a new key.
- 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 /monitors | List your monitors with status, response time, uptime and expiry details. |
|---|---|
GET /monitors/{id} | One monitor. |
POST /monitors | Add a monitor. Send JSON with at least type and target. |
POST /monitors/{id}/pause | Pause 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=down | An example event, so you can see the fields before a real one arrives. |
GET /me | Check 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.
| 400 | The 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. |
| 402 | The account has reached its monitor limit. See Plans and limits. |
| 403 | For hooks: confirm your email address first. Otherwise the account is suspended; contact support. |
| 404 | No monitor or hook with that id in this account. |
| 422 | A field is missing or not accepted. The error says which, for example “A port check needs a port number.” |
| 429 | Too many requests: wait a minute, or 15 minutes after many wrong keys. Also returned when the account already has 50 hooks. |
Still stuck? Email [email protected] and say which guide you were following.