API Documentation

1. Base URL

All API requests are made to:

https://api.kawze.com

A quick way to confirm connectivity and check the running API version is GET /v1, which doesn't require authentication:

curl https://api.kawze.com/v1

2. Authentication

Every other endpoint requires an API key, sent as a bearer token in the Authorization header:

curl https://api.kawze.com/v1/monitors \
  -H "Authorization: Bearer kawze_live_<your-key>"

Create and manage API keys from Account › Admin APIs once you're logged in. Each key is issued with a role - read, write, or admin - which gates what it can do using the same permission checks as a human account member. Keys can't be issued with billing or owner access, so a leaked key can never touch your subscription or account ownership.

You can reveal or regenerate a key later from the same page if you need to see it again or rotate it. Revoke a key at any time if it's no longer needed or may have leaked.

Admin keys (this page) cover /v1/account, /v1/monitors, /v1/status, and /v1/outages below. A separate kind of key, scoped only to sending heartbeat pings, is created from Account › Heartbeat APIs - see section 7. The two aren't interchangeable: an admin key can't send a heartbeat ping, and a heartbeat key can't read or write anything else.

3. Errors

Every response includes a status field, either "ok" or "error". Error responses also include a human-readable message:

{
  "status": "error",
  "message": "You do not have permission to update monitors on this account"
}

Common status codes: 400 bad request or not authenticated, 403 the key's role doesn't permit the action, 404 not found.

4. Account

Returns the account your key belongs to, and its members.

5. Monitors

Lists every monitor on the account.

Returns a single monitor.

A super trimmed-down version of /v1/monitors - just each monitor's id, name, and status (up, down, issue, or paused for a disabled monitor). Good for a quick "is everything up" check or a status widget that doesn't need every monitor's full configuration.

curl https://api.kawze.com/v1/status \
  -H "Authorization: Bearer kawze_live_<your-key>"

{
  "status": "ok",
  "monitors": [
    { "id": "...", "name": "Marketing site", "status": "up" },
    { "id": "...", "name": "API", "status": "down" }
  ]
}

Creates a monitor. Requires write role or higher. Body is { "monitor": { ... } } - the monitor shape depends on type (http, heartbeat, domain, timings, cache-warming, or tcp). A minimal HTTP monitor:

curl -X POST https://api.kawze.com/v1/monitors \
  -H "Authorization: Bearer kawze_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "monitor": {
    "type": "http",
    "name": "Marketing site",
    "url": "https://example.com",
    "intervalSeconds": 60,
    "regions": ["uk"]
  }
}'

{
  "status": "ok",
  "id": "652f1c2e9a1b2c0012345678"
}

Server-managed fields (status, enabled, lastChecked, and similar) are always assigned by the server and ignored if sent - see the full field reference for each monitor type in the dashboard's monitor editor.

Updates a monitor. Requires write role or higher. Same body shape as create. PUT and PATCH on the same path do the exact same full-replace update, for tooling that expects those verbs instead of POST.

Deletes a monitor. Requires write role or higher.

6. Monitor type field reference

Every configurable field for a POST /v1/monitors body, one monitor type at a time - pick a type to see its full example.

{
  "monitor": {
    "type": "http",
    "name": "Homepage",
    "tags": [
      "prod"
    ],
    "groups": [],
    "notifications": [],
    "downAlertThreshold": 1,
    "intervalSeconds": 60,
    "url": "https://example.com",
    "method": "GET",
    "headers": [],
    "body": {
      "type": "none"
    },
    "auth": {
      "type": "none"
    },
    "timeoutSeconds": 30,
    "followRedirects": true,
    "expectedStatusCodes": [
      "2xx"
    ],
    "cacheBreaking": false,
    "overrideUserAgent": false,
    "userAgent": "",
    "keywordMatch": {
      "keyword": "Welcome",
      "shouldContain": true
    },
    "regions": [
      "uk"
    ]
  }
}

7. Alerts (Email & SMS)

There's no separate "alerts" endpoint - who gets notified, on which channel, and for which statuses lives directly on the monitor's own notifications field, so it's read and written through /v1/monitors like any other field:

{
  "notifications": [
    {
      "userId": "<a member's userId from GET /v1/account>",
      "channels": [
        { "channel": "email", "statuses": ["down"] },
        { "channel": "sms", "statuses": ["down"] }
      ]
    }
  ]
}

statuses accepts up/down everywhere, plus dnsIssue/sslIssue on a domain monitor, and resourceError/fetchError/jsError on a visitor monitor - only include the ones you actually want that member paged for. Repeat the whole object per team member to notify more than one person, and their userId comes from that same GET /v1/account response's members list.

Slack, Microsoft Teams, and outgoing webhooks are configured separately from notifications - see the next section.

8. Slack, Teams & webhooks

Unlike email/SMS, Slack and Teams alerts aren't a field on the monitor itself - they're their own per-monitor resource, since each depends on an account-level integration (a connected Slack workspace or Teams webhook) that has to exist first. Connecting that integration is dashboard-only - Integrations › Slack and Integrations › Teams - but once it's connected, every monitor's alert on/off, channel and mentions are yours to manage over the API.

Slack

Returns the monitor's Slack alert config, if one has been set.

Creates or updates it. Requires write role or higher. channelId/channelName default to the account's default Slack channel when omitted. mentions.userIds only accepts raw Slack member IDs (e.g. "U0123ABCD"), not display names - find them in Slack via a member's profile › "Copy member ID".

curl -X PUT https://api.kawze.com/v1/monitors/652f1c2e9a1b2c0012345678/slack-alert \
  -H "Authorization: Bearer kawze_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "channelId": "C0123ABCD",
  "channelName": "#alerts",
  "enabled": true,
  "mentions": { "userIds": ["U0123ABCD"], "here": false, "channel": false }
}'

{
  "status": "ok"
}

Microsoft Teams

Returns the monitor's Teams alert config, if one has been set.

Creates or updates it. Requires write role or higher. On/off only - unlike Slack there's no channel to pick, a Teams webhook always posts to whichever channel it was created in.

curl -X PUT https://api.kawze.com/v1/monitors/652f1c2e9a1b2c0012345678/teams-alert \
  -H "Authorization: Bearer kawze_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'

{
  "status": "ok"
}

Webhooks

Webhooks are reusable across monitors, so they're their own account-level resource rather than a per-monitor setting - create one, then attach it to any number of monitors by including its _id in that monitor's webhookIds array (via /v1/monitors above).

Lists the account's webhooks.

curl https://api.kawze.com/v1/webhooks \
  -H "Authorization: Bearer kawze_live_<your-key>"

{
  "status": "ok",
  "webhooks": [
    { "_id": "652f4c1e9a1b2c0012347777", "label": "Incident bot", "url": "https://example.com/hooks/kawze", "method": "POST", "enabled": true }
  ]
}

Creates a webhook. Requires write role or higher. headers is an object of header name to value; bodyTemplate is optional raw text/JSON.

curl -X POST https://api.kawze.com/v1/webhooks \
  -H "Authorization: Bearer kawze_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Incident bot",
  "url": "https://example.com/hooks/kawze",
  "method": "POST",
  "expectedStatusCodes": ["200", "2xx"],
  "keywordMatch": { "keyword": "ok", "shouldContain": true }
}'

{
  "status": "ok"
}

Updates a webhook. Requires write role or higher. Only the fields included in the body are changed.

Deletes a webhook. Requires write role or higher. Also detaches it from every monitor that had it selected.

9. Outages

Lists incidents across all of the account's monitors.

Returns a single incident, including its comment thread.

10. Heartbeat

Marks a heartbeat monitor up, same effect as calling its own per-monitor ping URL (shown on the monitor's Heartbeat APIs card). Only works with a heartbeat- purpose key - an admin key gets 403. No body required:

curl -X POST https://api.kawze.com/v1/heartbeat/652f1c2e9a1b2c0012345678 \
  -H "Authorization: Bearer kawze_live_<your-heartbeat-key>"

{
  "status": "ok"
}

12. Notes

Enabling/disabling, duplicating a monitor, and the ad-hoc URL checker aren't part of the public API yet - those stay dashboard-only for now. Connecting Slack or Teams to the account in the first place is also dashboard-only (section 8) - only the per-monitor alert config is available over the API.