# Get from zero to first monitor in under 3 minutes
> Everything the dashboard does is available over API, MCP, or GitHub Action.
## Get an API key
Sign in with GitHub, Google, Microsoft, or email, then create a key and label it for your environment.
```bash
Authorization: Bearer mk_live_...
```
1. Go to [my.monitive.com](https://my.monitive.com)
2. Click **Continue with GitHub**
3. Create an API key and label it (e.g. `ci-prod`, `local-dev`, `mcp`)
---
## Create your first monitor
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"myapp","url":"https://myapp.com/healthz","type":"http"}'
```
The hostname must resolve at creation time — typos and unreachable targets fail immediately. The response wraps the monitor record and its first state snapshot:
```json
{
"monitor": {
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "myapp",
"url": "https://myapp.com/healthz",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true
},
"state": {
"status": "up",
"last_check_at": "2026-05-07T10:21:01Z",
"evidence_buffer": [
{ "region": "EU", "status_code": 200, "ttfb_ms": 182 }
]
}
}
```
Capture the ID for the rest of the Quickstart:
```bash
MONITOR_ID=1287
```
---
## Check current status
Capture the monitor ID from the create response, then poll it:
```bash
curl https://api.monitive.com/api/v1/monitors/$MONITOR_ID \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
---
## Add a webhook
Webhooks are account-level recipients, reusable across any number of monitors — not scoped to one monitor. Create one:
```bash
curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"ops-webhook","type":"webhook","config":{"url":"https://hooks.example.com/incident"}}'
```
The response includes the recipient's `id` and a plaintext `secret` — copy the secret now, since no later read of this recipient returns it. Capture the ID:
```bash
RECIPIENT_ID=42
```
`PUT` on a monitor's recipients replaces the complete set, so read the monitor's current recipients first — a brand-new monitor can already carry the account's default recipients:
```bash
curl https://api.monitive.com/api/v1/monitors/$MONITOR_ID/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
Then submit the full set, adding the new recipient to whatever came back:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/$MONITOR_ID/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"recipients":[{"id":'"$RECIPIENT_ID"',"grace_s":120}]}'
```
See [Webhooks](/docs/webhooks/) for signature verification and the account-wide `/api/v1/webhook-deliveries` log, and [Choose who gets alerts](/docs/guides/alert-recipients/) for the full attach/detach model. The older `PUT /api/v1/monitors/{monitorID}/webhook` endpoint still works but is deprecated — see [Legacy monitor-scoped webhook endpoint](/docs/webhooks/#legacy-monitor-scoped-webhook-endpoint-deprecated).
---
## Connect via MCP
Set up Monitive as an MCP server in your preferred tool:
- **Claude** — Add the MCP server in Claude Desktop settings or Claude Code
- **ChatGPT** — Configure via the ChatGPT plugin/MCP settings
- **Cursor** — Add to `.cursor/mcp.json`
- **OpenAI API** — Use the MCP endpoint in your tool configuration
See the [MCP docs](/docs/mcp/) for detailed setup instructions per host.
---
## Use in GitHub Actions
```yaml
- name: Verify deploy health
uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-id: ${{ vars.MONITOR_ID }}
timeout: 120
```
This step waits up to 120 seconds for the monitor to report healthy, then fails the workflow if it doesn't recover. See the [GitHub Action docs](/docs/github-action/) for advanced options.
---
:::tip[Working examples]
Full runnable copies of every snippet on this page — GitHub Actions workflows, MCP setup, webhook relay scripts, and language examples — live at [github.com/uptimemonitoring/examples](https://github.com/uptimemonitoring/examples).
:::
---
# Sign in
> Sign in to Monitive with GitHub, Google, Microsoft, or email, and link a second method to an existing account.
## What it does
Monitive supports GitHub, Google, Microsoft, or email sign-in. None of the methods use a password. You can also link a second method to an account you already use, from account settings.
Each method resolves to its own identity on your account: a GitHub login resolves by your GitHub user ID, a Google login resolves by your Google account's subject identifier, and email sign-in resolves by the address itself. **Signing in with a different method than the one you used originally only finds your existing account automatically in specific cases** — see [When matching email addresses link automatically](#when-matching-email-addresses-link-automatically) below. Outside those cases, see [Linking a second method to an existing account](#linking-a-second-method-to-an-existing-account) before you try a different provider on an account you already use.
## Set it up in the app
1. Go to [my.monitive.com](https://my.monitive.com).
2. Pick GitHub, Google, Microsoft, or email:
- Click **Continue with GitHub** to authorize with GitHub.
- Click **Continue with Google** to authorize with Google.
- Enter your address under **Email** and click **Send sign-in link**.
3. For email sign-in, check your inbox: either follow the link, or enter the 6-digit code on the page you're sent back to. The link and code both expire in 10 minutes.

### Linking a second method to an existing account
If you already have an account — say, from GitHub sign-in — and you want to add Google or email as a second way in:
1. Sign in with the method you already use first.
2. Go to **Settings** and find **Connected identities**.
3. Click **Add Google**, or enter an address under **Email** and click **Add email**, then confirm it the same way you would for a fresh email sign-in.
Do this instead of signing in directly with the new method on its own — outside the specific cases described below where matching email addresses link automatically, a direct sign-in with an unlinked method creates a second, empty account with no monitors.
**If the identity is already linked to a different account:** linking fails. You'll see this if you try to add a Google account or an email address that's already tied to a different Monitive user — including a Google account whose own verified email happens to match your current account's address. There is no merge path for this case today: the two accounts' monitors and recipients stay separate. If you hit this, decide which account you want to keep using and sign in to that one directly with the method already linked to it.
### When matching email addresses link automatically
Whether a first sign-in with a new method lands on your existing account or creates a fresh, empty one depends on the method and, for Google, the address:
- **GitHub:** a first sign-in for a GitHub account links to an existing user who already holds that account's verified primary email as a verified email identity and has no GitHub identity of their own yet. GitHub sign-in requires a verified primary email — GitHub reports none, or only an unverified one, and the sign-in is refused outright.
- **Google:** a first sign-in links to an existing user who holds the same verified address and has no Google identity yet, but only when the address is `gmail.com` or `googlemail.com`, or a Google Workspace account whose domain matches the address. Any other verified address creates a separate user instead, with no link.
- **Email code:** resolves by the address alone.
Outside those cases, there's no automatic link. If the identity isn't already linked to a different account, use the linking steps above instead. If the address is already attached to a different account's GitHub or Google identity, linking will fail — sign in to that other account directly with the method already linked to it instead; there's no merge path between the two accounts.
## Do the same through the API or MCP
There isn't an API or MCP equivalent for this guide — signing in and linking identities require completing an OAuth consent screen or clicking an emailed link in a browser, and the identity-linking endpoints (`POST /api/v1/me/identities/github`, `/google`, `/email/start`, `/email/verify`) only accept a browser dashboard session. Calling any of them with an API key or an MCP/OAuth access token returns `403 {"error":"session_required"}`.
Once you're signed in, the full set — creating monitors, managing recipients, querying incidents — is available over the REST API using an API key. MCP covers a narrower surface: monitor operations (create, read, update, delete, list) and incident operations (list), plus attaching an already-created recipient to a new monitor via `create_monitor`'s `recipient_ids`/`recipients` arguments. Creating or confirming recipients, and changing an existing monitor's recipients, has no MCP tool today — use the REST API or dashboard for those. See [API keys](/docs/api-keys/) for API key creation and format, [Use Monitive through MCP](/docs/mcp/) for connecting an agent, and [Choose who gets alerts](/docs/guides/alert-recipients/) for recipient attachment semantics.
## Plan limits
Sign-in itself carries no plan limit. Once signed in, see [API keys](/docs/api-keys/) for the API key limit (10 keys per account) and the [monitors guide](/docs/monitors/) for monitor caps.
## Troubleshooting
**"This identity is already linked to another user."** You tried to link a Google account or an email address already tied to a different Monitive account. Sign in to that other account directly instead, or decide which of the two accounts to keep — there's no built-in merge.
**I signed in with Google/email and my monitors are gone.** You likely landed in a second, new account rather than your original one. Sign out, sign back in with the method you used originally (GitHub, most likely), and link the new method from **Settings → Connected identities** instead of signing in with it directly.
**The sign-in link or code expired.** Links and codes are valid for 10 minutes. Click **Use a different address** (or just retry) to request a new one.
**I got rate-limited.** Email sign-in and linking share a per-address and per-process sender limit. Wait and retry — the page shows how long.
---
# Send a custom HTTP request
> Configure an HTTP monitor's method, body, headers, and timeout in the dashboard or via the API and MCP.
## What it does
An HTTP monitor can send more than a plain `GET`. Four fields control the request: **method** (one of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS` — there's no `HEAD`), **body**, **headers** (name/value pairs), and **timeout** in seconds (1-30, default 30). These only apply to `type: "http"` monitors.
A header value is never returned by the API once it's saved — a response shows `{"name": "...", "value_set": true}` for a header with a stored value, or `value_set: false` for a header stored with an empty value. Either way, the value itself isn't serialized again. That covers API and MCP reads only: it doesn't change where the probe sends the value. Every configured header goes out on every request the probe makes, including after the monitored URL redirects elsewhere — point the monitor at the final URL rather than one that redirects to a different host.
The **body** is not write-only — it's returned verbatim in every read. Put a credential in a header, never in the body.
No `Content-Type` header is added automatically. If your endpoint needs one, add it yourself.
The configured method, body, and headers go out on creation (the API runs an immediate test check before returning), on every scheduled check, every manual **Run test**, and the confirmation checks other regions run after a failed check — not just once. Point a non-`GET` request at an endpoint that's safe to call repeatedly, such as a dedicated health check, not one that changes data on every call.
## Set it up in the app
1. In the dashboard, click **New monitor**.
2. Set **Type** to **HTTP** and fill in **Name** and **URL**.
3. Click **Advanced** to expand the extra fields.
4. Set **Method** to the HTTP method you need.
5. Set **Timeout (s)** if 30 seconds is too long or too short for your endpoint.
6. For `POST`, `PUT`, `PATCH`, or `DELETE`, a **Body** field appears — enter the request body.
7. Under **Headers**, click **Add header** for each header, and fill in its name and value.
8. Click **Add** to save — this invokes the target immediately with the configured method, body, and headers, before the first scheduled check runs.

Once the monitor is saved, use **Run test** to send an ad-hoc check. It sends the *saved* request — method, body, headers, and timeout exactly as they're stored — so save your edits first; the test endpoint doesn't see unsaved changes in the form.
## Do the same through the API or MCP
`POST /api/v1/monitors` also invokes the target immediately, with the request below, before it returns:
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "api-health-check",
"url": "https://api.example.com/health",
"type": "http",
"method": "POST",
"body": "{\"ping\":true}",
"headers": [
{"name": "Content-Type", "value": "application/json"},
{"name": "Authorization", "value": "Bearer ..."}
],
"timeout_sec": 10
}'
```
The response wraps the monitor in the same `monitor`/`state` envelope as [Create a monitor](/docs/monitors/#create-a-monitor); headers are echoed under `monitor.headers`, without their values (abridged):
```json
{
"monitor": {
"id": 1287,
"headers": [
{"name": "Content-Type", "value_set": true},
{"name": "Authorization", "value_set": true}
]
},
"state": { "status": "up", "last_check_at": "2026-05-07T10:21:01Z" }
}
```
`value_set` is `false` when a header is stored with an empty value — the header still exists and is still sent; it just has nothing after the name.
To change a monitor with `PUT`, send a complete `headers` array — it replaces the whole list. Omit `value` on an entry to keep that header's already-stored value instead of resending it:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"headers": [
{"name": "Content-Type", "value": "application/json"},
{"name": "Authorization"}
]
}'
```
If the URL's scheme, host, or port changes in the same request, every header's value must be resent — keeping by omission isn't allowed across a destination change.
Through MCP, `create_monitor` and `update_monitor` accept the same `method`, `body`, `headers`, and `timeout_sec` fields, with the same keep-by-name rule for `update_monitor`'s headers. [Use Monitive through MCP](/docs/mcp/) lists the available tools, and [Monitors](/docs/monitors/) covers the shared create/update envelope — for the complete field-by-field request and response schema, see the [API reference](/api-reference/).
## Plan limits
- Up to 5 non-`GET` monitors per account, counting disabled ones. Creating or updating a sixth returns `409` with `non-GET monitor limit reached (max 5 per account)`.
- Body: up to 4,096 characters.
- Headers: up to 20 entries.
- Headers total size: 8,192 bytes, counting each header's name length + 2 + value length.
- `timeout_sec`: 1 to 30.
- Blocked header names, matched case-insensitively: `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`.
- Header names must be valid RFC 7230 tokens. Header values can't contain CR, LF, NUL, or other control characters — a literal tab is allowed.
See [Monitors](/docs/monitors/) for the shared monitor limits (name length, monitor count caps).
## Troubleshooting
**"method must be one of: GET, POST, PUT, DELETE, PATCH, OPTIONS."** The `method` you sent isn't in the allowed list — note there's no `HEAD`.
**"body must be 4096 characters or less."** Your request body is too long — trim it or move data to a header.
**"headers must be 20 or fewer."** Combine or drop headers to get under the cap.
**"header \"X\" is not allowed."** You sent one of the blocked names (`Host`, `Content-Length`, `Transfer-Encoding`, `Connection`). These are controlled by the HTTP client itself and can't be overridden.
**"header \"X\" has no stored value to keep."** You sent a `PUT` with a header entry that omits `value`, but no value is stored for that name yet — every new header name needs a `value` the first time.
**"headers must be resent with their values when the URL's scheme, host, or port changes."** You changed the monitor's destination in the same request that also touched headers without `value`. Resend every header's actual value alongside the new URL.
**"timeout_sec must be between 1 and 30."** Pick a value in that range.
**The server returns an error about a missing or wrong `Content-Type`.** The probe doesn't add one automatically — add a `Content-Type` header yourself that matches your body format.
**Run test doesn't reflect an edit I just made.** Save the monitor first — **Run test** sends the saved request, not the form's current unsaved state.
---
# Monitor a TCP port
> Create a TCP monitor in the dashboard or via the API and MCP, and see the full list of ports the API allows.
## What it does
A TCP monitor connects to a host and port on each check interval and confirms the connection succeeds — no HTTP request, no response body, just "can we open a socket." Use it for databases, SSH, SMTP, or any other service that doesn't speak HTTP.
## Set it up in the app
1. In the dashboard, click **Add** to create a monitor.
2. Set **Type** to **TCP**.
3. Enter a **Name** (for example `prod-postgres`).
4. Enter the target in the **Host:port** field, for example `db.example.com:5432`.
5. Click **Add**.

The dashboard's port field is free text with a hint listing a curated set of common ports — see [Plan limits](#plan-limits) below for why the real, complete allowed list is longer than the hint.
## Do the same through the API or MCP
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-postgres",
"url": "tcp://db.example.com:5432",
"type": "tcp"
}'
```
The `url` field takes `host:port` or `tcp://host:port` — no path, query, or scheme other than `tcp://`. `expected_status` and `body_match` are ignored for `type: "tcp"`. TCP and ping monitors return `state.status: "unknown"` in the create response; the next scheduled check fills in `up` or `down`. See [Monitors](/docs/monitors/) for the full create/update/delete reference.
Through MCP, ask your agent to create a monitor and give it the host:port target and `type: tcp`; the `create_monitor` tool accepts the same `url`/`type` shape. See [Use Monitive through MCP](/docs/mcp/).
## Plan limits
The account's real, complete allowed-port list comes from um-api's `checker.AllowedTCPPortsList()` (`internal/checker/ssrf.go`), backed by the `allowedTCPPorts` map in `internal/checker/checker.go`. Don't treat the list below as fixed — it's a snapshot of what `AllowedTCPPortsList()` returns as of this writing, not a forward compatibility promise:
```
21, 22, 25, 80, 110, 143, 443, 465, 587, 993, 995, 2222,
3000, 3306, 5000, 5432, 6379, 8000, 8080, 8443, 8888, 27017
```
The dashboard's port hint shows a narrower, curated subset of eight common ports (`80, 443, 8080, 8443, 3000, 5000, 8000, 8888`) as a convenience — it's not the complete list, and it doesn't validate the port itself. The API accepts any port from the complete list above, whether or not the dashboard's hint mentions it.
If you create a monitor with a port outside the complete list, the API rejects it with a `400` whose message echoes the same list:
```json
{"error": "port 11211 is not allowed for TCP monitors; allowed ports: 21, 22, 25, 80, 110, 143, 443, 465, 587, 993, 995, 2222, 3000, 3306, 5000, 5432, 6379, 8000, 8080, 8443, 8888, 27017"}
```
See [Monitors](/docs/monitors/) for the shared monitor limits (name length, monitor count caps).
## Troubleshooting
**"port is not allowed for TCP monitors."** The port you targeted isn't on the allowed list above. Check the exact port number in your `url` — a typo'd port (like a container's internal port instead of its published one) is a common cause.
**The monitor shows `unknown` right after creation.** That's expected for TCP monitors — the immediate test check that HTTP monitors get doesn't apply here. Wait for the next scheduled check (up to `interval_sec` seconds later).
**Connection refused or timeout, but the port is allowed.** The allowed-port check only confirms the port is on Monitive's list — it doesn't guarantee the target host accepts connections on it. Confirm the service is actually listening and reachable from the public internet; Monitive's probes can't reach hosts behind a private network or firewall allowlist that excludes them.
---
# Monitor a host with ping
> Create a ping (ICMP) monitor in the dashboard or via the API and MCP.
## What it does
A ping monitor sends ICMP echo requests to a hostname or IP address on each check interval and confirms the host responds — basic reachability, no port, no application-level check. Use it for infrastructure you want a heartbeat on without an HTTP endpoint or an open TCP port.
## Set it up in the app
1. In the dashboard, click **Add** to create a monitor.
2. Set **Type** to **Ping**.
3. Enter a **Name** (for example `edge-router-1`).
4. Enter the target in the **Hostname** field, for example `edge1.example.com` — no scheme, path, or port.
5. Click **Add**.

## Do the same through the API or MCP
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "edge-router-1",
"url": "edge1.example.com",
"type": "ping"
}'
```
The `url` field for `type: "ping"` is a bare hostname or IP literal — no scheme, path, or port. `expected_status` and `body_match` are ignored. As with TCP monitors, the create response returns `state.status: "unknown"`; the next scheduled check fills in `up` or `down`. See [Monitors](/docs/monitors/) for the full create/update/delete reference.
Through MCP, ask your agent to create a monitor with `type: ping` and the bare hostname; the `create_monitor` tool accepts the same shape. See [Use Monitive through MCP](/docs/mcp/).
## Plan limits
The ping target's hostname is capped at 253 characters (`pingHostMaxLen` in um-api's `internal/checker/ssrf.go`) — the standard DNS full-name length limit, including label-separating dots. A hostname longer than that is rejected before a check ever runs.
See [Monitors](/docs/monitors/) for the shared monitor limits (name length, monitor count caps, 60-second minimum check interval).
## Troubleshooting
**"host must be 253 characters or fewer."** Your target hostname exceeds the DNS name-length limit. Double check you haven't pasted a URL (with a scheme or path) into the hostname field by mistake — only a bare hostname or IP literal is accepted.
**The monitor shows `unknown` right after creation.** Expected — ping monitors don't get the immediate test check HTTP monitors do. Wait for the next scheduled check.
**ICMP is blocked but the host is actually up.** Some hosts and networks drop ICMP echo requests entirely (security policy, cloud provider default, etc.) even though the service behind them is healthy. If that's the case for your target, an [HTTP](/docs/monitors/) or [TCP](/docs/guides/tcp-monitors/) monitor against an actual service port is more reliable than ping.
---
# Choose who gets alerts
> Attach and detach recipients on a monitor, understand the full-replacement API semantics, and what happens to queued deliveries when you do.
## What it does
A recipient is a destination for alerts, created once at the account level and then attached to any number of monitors. Each monitor has its own set of attached recipients; attaching or detaching a recipient from one monitor doesn't affect its attachment to any other monitor. The dashboard supports creating **webhook**, **email**, **Slack**, and **PagerDuty** recipients today — see the [Slack alerts guide](/docs/guides/slack-alerts/) and [Send alerts to PagerDuty](/docs/guides/pagerduty-alerts/) for each of those recipient types' own setup, API, and troubleshooting details.
Every alert waits out a two-minute grace period: an alert goes out when the monitor has stayed down for two minutes, and a monitor that recovers inside that window sends no alert.
**Never attach a Slack or PagerDuty destination to a `type: "webhook"` recipient.** Monitive's webhook payload (`event`, monitor fields, delivery metadata — see [Webhooks](/docs/webhooks/#payload-format)) isn't the shape either destination expects: Slack silently discards it, and PagerDuty's Events API rejects it outright. For a destination with no native recipient type (Discord, Pushover, ntfy, and others), use the open-source [alert-bridge](/docs/alert-bridge/) relay instead of pointing a webhook recipient's URL directly at it.
## Set it up in the app
### Create an account-level recipient
1. Go to **Recipients** in the dashboard and click **Create recipient**.
2. Choose **Webhook**, **Email**, **Slack**, or **PagerDuty** (see [Send alerts to PagerDuty](/docs/guides/pagerduty-alerts/)), fill in the URL, email address, or integration key, pick which events to notify on (**Down**, **Up**, **Flapping**), and optionally turn on **Default for new monitors**.
3. Click **Create recipient**.
For a webhook recipient, you'll see **Your recipient secret** once — copy it now, since Monitive won't show it again. For an email recipient, you'll see **Confirmation sent to `
`** — alerts don't start until that confirmation is followed (see the [email alerts guide](/docs/guides/email-alerts/) for that lifecycle). A Slack recipient is active immediately, with no secret shown — see the [Slack alerts guide](/docs/guides/slack-alerts/).
### Attach or detach recipients on a monitor
1. Open the monitor and find its **Recipients** section.
2. Check or uncheck recipients, then click **Save**.

If no recipient ends up attached and the monitor is enabled, the dashboard shows "No one is listening to this monitor" — a safety check that the monitor isn't silently unmonitored by a human.
## Do the same through the API or MCP
**`PUT /api/v1/monitors/{monitorID}/recipients` replaces the monitor's complete recipient set — it is not a merge.** Sending just a new recipient's id detaches every other recipient currently attached to that monitor. Always read the current set first, add to it, and submit the full result:
```bash
# 1. Read the monitor's current recipients
CURRENT=$(curl -s https://api.monitive.com/api/v1/monitors/1287/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY")
# -> {"recipients": [{"id": 10, "grace_s": 120}, {"id": 11, "grace_s": 120}]}
# 2. Build the full set from what the GET actually returned — append the
# new recipient (42) to .recipients rather than retyping it, so existing
# attachments survive even if the current set wasn't what you expected.
# Requires jq.
BODY=$(echo "$CURRENT" | jq '{recipients: (.recipients + [{id: 42, grace_s: 120}])}')
curl -X PUT https://api.monitive.com/api/v1/monitors/1287/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d "$BODY"
```
Each `recipients` entry's `grace_s` is that two-minute grace in seconds. `120` is the only value the API accepts, and a request that sets any other value is refused. `down_delay_s` is a deprecated alias for `grace_s` that the API still accepts and returns.
**This read-then-write sequence has no concurrency protection.** The `PUT` carries no version, ETag, or `If-Match` precondition, so two clients that each read the same list and then submit their own addition can race: whichever `PUT` lands second silently overwrites the first, and the recipient the first client added is detached again — along with that recipient's queued deliveries. Edit a monitor's recipients from one place at a time, and re-read the result after saving to confirm it matches what you intended.
Creating a monitor can also attach recipients directly, through `create_monitor`'s `recipient_ids` or `recipients` arguments (mutually exclusive — specifying both is an error); `recipients` entries take the same `id` and `grace_s` fields as the REST `PUT`, with `grace_s` fixed at `120`. There's no MCP tool for changing an existing monitor's recipients after creation — `update_monitor` doesn't take a recipients argument — so use the REST `PUT` endpoint above, or the dashboard, for that. See [Use Monitive through MCP](/docs/mcp/).
For creating a webhook recipient directly through the API, and its payload format and signature verification once it's attached, see [Webhooks](/docs/webhooks/#create-an-account-level-webhook-recipient).
### Detaching a recipient vs. deleting it
Detaching a recipient from one monitor (an updated `PUT` that no longer includes its id) deletes only that monitor's own queued (`pending`/`retrying`) deliveries for that recipient — its attachment to any other monitor, and that monitor's own queued deliveries, are untouched. A delivery a worker already claimed just before the detach commits can still complete; whether it's recorded in the delivery log afterward depends on which operation's database write lands first, so you may or may not see it in the log either way.
Deleting the account-level recipient (`DELETE /api/v1/recipients/{recipientID}`) cascades: it detaches the recipient from every monitor that referenced it, and deletes only its pending/retrying deliveries across all of them, the same way a single detach would — just applied everywhere at once. Completed, failed, and superseded delivery history for that recipient survives the deletion; it ages out later under the account's delivery-log retention window (see [Webhooks](/docs/webhooks/)), and those historical rows can keep referencing the now-deleted recipient's id.
## Plan limits
A recipient name is capped at 255 bytes (`recipientNameMaxLen` in um-api's `internal/api/recipients.go`), enforced on the raw bytes before UTF-8 validity is checked — not 255 characters. A name using non-ASCII characters (for example, emoji or CJK text) reaches that ceiling at fewer characters than 255.
See [Monitors](/docs/monitors/) for monitor count caps, and [Webhooks](/docs/webhooks/) for the account-wide delivery log, which every recipient type shares. Retry eligibility, though, is type-specific: a webhook recipient retries any non-2xx response or timeout (see [Webhooks' retry policy](/docs/webhooks/#retry-policy)), while a Slack recipient retries only a transport error, `429`, or `5xx` — any other non-2xx fails immediately (see the [Slack alerts guide](/docs/guides/slack-alerts/)).
## Troubleshooting
**My `PUT` detached recipients I didn't mean to remove.** You (or another client) submitted a partial recipient set. `PUT` always replaces the complete set — read the current set first, then submit the full list with your change included, as shown above.
**A teammate's change to a monitor's recipients disappeared.** Two edits raced: both of you read the same list, each added something different, and the second `PUT` to land won, overwriting the first's addition. There's no built-in locking for this — coordinate changes to one monitor's recipients from one place at a time, and re-read after saving.
**A recipient got detached and I still see a delivery for it afterward.** That's the documented race: a delivery a worker had already claimed right before the detach can still complete and get recorded, even though the detach already ran. This is expected, not a bug.
**I deleted a recipient and its old deliveries still show up.** Deleting a recipient removes only its pending/retrying deliveries. Completed, failed, and superseded history survives until it ages out under the retention window — it isn't erased on delete.
---
# Send alerts to email
> Create an email recipient, confirm it, attach it to monitors, and handle the pending-to-active confirmation lifecycle.
## What it does
An email recipient sends outage and recovery alerts to an address you choose, instead of (or alongside) a webhook, [Slack](/docs/guides/slack-alerts/), or [PagerDuty](/docs/guides/pagerduty-alerts/) recipient — the other recipient types the dashboard can create today. Unlike a webhook or Slack recipient, an email recipient has a confirmation step: it starts `pending` and sends nothing until the mailed confirmation link is followed.
## Set it up in the app
1. Go to **Recipients** and click **Create recipient**.
2. Choose **Email**, enter the address, pick which events to notify on, and click **Create recipient**.
3. You'll see **Confirmation sent to ``** — alerts start once the recipient confirms. Click **Done**.
4. Check that address's inbox and follow the confirmation link.
5. Attach the recipient to a monitor from that monitor's **Recipients** section, the same way you would any other recipient type — see the [alert recipients guide](/docs/guides/alert-recipients/).
A recipient's status shows on its row in the dashboard: **active**, **awaiting confirmation** (`pending`), or **unsubscribed** (`disabled`).

## Do the same through the API or MCP
```bash
curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "on-call",
"type": "email",
"config": {"address": "oncall@example.com"},
"events": ["down", "up", "flapping"]
}'
```
The response's `status` field reads `"pending"` immediately after creation — a `201` here does not mean the confirmation mail actually arrived (see [Troubleshooting](#troubleshooting)). Attach it to a monitor using the full-replacement `PUT` endpoint described in the [alert recipients guide](/docs/guides/alert-recipients/).
Through MCP, `create_monitor`'s `recipients` argument can attach an existing email recipient by id at monitor-creation time; creating the email recipient itself, and resending or checking its confirmation, has no MCP tool today — use the REST API or the dashboard for those.
## Plan limits
The default email daily cap is 200 sends per account per UTC calendar day (`DefaultEmailDailyCap` in um-api's `internal/webhook/delivery.go`) — the dispatcher can override this default per deployment. A few things this number is *not*:
- **It's account-level, not per-recipient.** All of an account's email recipients share the same 200-send counter for the day.
- **It's a hard stop at the boundary, not a queue.** A delivery that arrives after the account has hit the cap for the UTC day is marked `failed` immediately and is not retried automatically once the next day's counter resets — a person has to notice and resend, or wait for the next qualifying event.
- **It's not an exact count of messages you'll receive.** Email delivery is at-least-once, like every other recipient type: if the send succeeds but the worker crashes before recording that outcome, the next poll can resend the same alert without consuming another cap slot. Don't treat 200 as a guaranteed, exact number of emails sent or received in a day.
See [Choose who gets alerts](/docs/guides/alert-recipients/) for the recipient name length limit (255 bytes) shared by every recipient type.
## Troubleshooting
**A recipient has been `pending` for a while and isn't getting alerts.** A `pending` recipient sends no alerts at all — it must be confirmed first. Check its status on the **Recipients** page, and resend the confirmation if needed (see below). Creating or changing an email recipient's address sends its confirmation mail *after* the API call already succeeded, and that send is best-effort: a successful response doesn't guarantee the mail arrived.
**Retrying my `PATCH` didn't resend the confirmation.** It won't — submitting the same, unchanged address again doesn't trigger a second confirmation mail. Use the dedicated resend endpoint instead:
```bash
curl -X POST https://api.monitive.com/api/v1/recipients/42/confirm/resend \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
This can return `202` (resent), `409` (two different meanings — see below), `429` (resent too recently — there's a 60-second cooldown, plus a per-address hourly rate limit; the response includes a `Retry-After` header), or `503` (the resend attempt itself failed to send). A `202` means a new confirmation mail was sent, not that the recipient is active again: it stays `pending`, sending nothing, until that new link is followed. Resend only accepts a recipient whose type is email and whose status still permits a fresh confirmation attempt — it has no effect on one that's already `disabled`, which this endpoint rejects outright.
A `409` here means one of two different things, and the response body doesn't always make the distinction obvious:
- **The recipient is already confirmed.** Nothing to do — it's `active`.
- **A concurrent resend, address change, or deletion invalidated this specific mailed link after it was sent.** This happens when the link was emailed successfully, but by the time the send finished, something else had already superseded the pending confirmation hash it carries — a second resend, an address change, or the recipient being deleted mid-flight. The mail arrived, but following that particular link returns an error rather than confirming.
Before retrying, re-fetch the recipient (`GET /api/v1/recipients/{recipientID}`) to find out which of these it was — a blind retry only works for one of the two causes:
- **It still exists and is `pending`.** The invalidation was a resend or an address change. Request another resend to get a link that's current.
- **It's gone (`404`).** It was deleted mid-flight — there's no recipient left for a resend to target, so requesting one just gets another `409`/`404`. Create a replacement recipient with the same `name`, `default`, and `events`, then reattach it to every monitor the deleted recipient was on (see [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp) for the read-merge-write `recipients` form), and have the owner follow the new confirmation link.
**A recipient is `disabled` and resend doesn't fix it.** A recipient reaches `disabled` only through its mailed unsubscribe link, and there is no API or dashboard action that re-enables it from there. The only recovery is to delete it and create a replacement — but deleting it first detaches it from every monitor it was on, so a careless delete-then-create leaves those monitors unalerted until you notice and reattach them by hand. There is no gap-free recovery from a disabled recipient — step 4 below attaches the replacement before it's confirmed specifically to minimize that window, not eliminate it:
1. Read and save the disabled recipient's `name`, `default`, `events`, and `monitor_ids` (`GET /api/v1/recipients/{recipientID}`).
2. Create the replacement email recipient with the same `name`, `default`, and `events`. It starts `pending`, same as any new email recipient.
3. **Attach the replacement to every saved monitor while it's still `pending`**, with `grace_s` set to `120`, using the read-merge-write `recipients` form from [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp). Attachment validation checks only recipient ownership, not status, so a `pending` recipient attaches exactly like an `active` one. Verify every attachment landed before continuing.
4. **Only now follow the replacement's confirmation link** so it reaches `active`. Attaching before confirming matters: a `pending` recipient sends nothing, so any event that occurs while it's still pending goes undelivered and isn't retried once it activates — but attaching first stops that gap from growing past confirmation. Confirming first and attaching afterward would leave that same gap open for the entire time it takes to migrate every monitor, instead of just until one confirmation click.
5. Once active, verify delivery with the recipient's test-send endpoint (`POST /api/v1/recipients/{recipientID}/test`) or a controlled down/up transition — not by waiting for the next check cycle.
6. Immediately before deleting the disabled recipient, re-read every affected monitor's `recipients` array directly and confirm the replacement is attached, retrying any monitor where it's missing. Separately, re-read the disabled recipient's own `monitor_ids`, in case a monitor was attached mid-recovery and missed your step 1 snapshot — migrate that attachment too.
7. Only then delete the disabled recipient.
This procedure assumes no other writer changes an affected monitor's recipients for its entire duration, not only at the start — step 6's re-read is a mitigation against a concurrent change, not a guarantee against one. No step here is atomic with another, so a crash partway through can leave some monitors still on the disabled recipient; re-check their attached recipients afterward.
**A monitor has email recipients attached but nobody's getting alerted.** A `pending` or `disabled` recipient doesn't make a monitor alert-capable, even though it's attached. Confirm the recipient is `active` before relying on it — attaching a recipient is not the same as it being able to send.
---
# Send alerts to Slack
> Create a Slack recipient from an incoming webhook URL, test it, attach it to monitors, and rotate the URL without losing the recipient.
## What it does
A Slack recipient delivers outage and recovery alerts straight to a Slack channel through a Slack incoming webhook — a destination um-api understands natively, not a generic `type: "webhook"` recipient pointed at Slack. **Never attach a Slack destination to a `type: "webhook"` recipient.** Monitive's webhook payload isn't the shape Slack expects, and Slack silently discards it. See [Choose who gets alerts](/docs/guides/alert-recipients/) for why a native recipient type exists for destinations like this one.
A Slack recipient is active the moment you create it — there's no confirmation step and no secret to copy, unlike an [email recipient](/docs/guides/email-alerts/) or a webhook recipient's signing secret.
## Set it up in the app
First, get an incoming webhook URL from Slack:
1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) (or open one you already have).
2. Turn on **Incoming Webhooks**.
3. Click **Add New Webhook to Workspace** and pick the channel there.
4. Copy the generated webhook URL — it looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`.
**Treat that URL as a credential.** Anyone who has it can post to the channel you picked — don't commit it, log it, or paste it somewhere public. If one ever leaks, revoke it in Slack's Incoming Webhooks settings and replace it on the recipient (see [Troubleshooting](#troubleshooting)).
Then, in the dashboard:
1. Go to **Recipients** and click **Create recipient**.
2. Choose the **Slack** tab, paste the webhook URL, pick which events to notify on, and optionally turn on **Default for new monitors**.
3. Click **Create recipient**. You'll see a **Recipient "…" created.** toast, and the dialog closes — the recipient is already `active`.

4. Before attaching it anywhere, use the **Send test** row action on the Recipients page to confirm Slack actually accepts the URL — see [Troubleshooting](#troubleshooting) for what a failed test looks like. A real alert sent through a recipient with a revoked or otherwise unusable URL fails immediately with no retry, so don't attach a recipient whose test hasn't passed; fix or replace the URL and test again first.
5. Once the test succeeds, attach it to a monitor from that monitor's **Recipients** section, the same way you would any other recipient type — see the [alert recipients guide](/docs/guides/alert-recipients/).
**Edit a Slack recipient.** The Webhook URL field starts blank, with the placeholder **Leave blank to keep the current URL** and a **Current: `https://hooks.slack.com/services/T…/B…/********`** line underneath showing the masked value um-api stores. Leave the field blank to keep the existing URL, or paste a new one to replace it — pasting the masked value back doesn't work (see [Troubleshooting](#troubleshooting)).
**Rotating the URL.** Saving a new URL in this field is the cutover, not a staged step — the moment you save, the recipient's live webhook is the new URL, before **Send test** has confirmed Slack accepts it. This sequence is not gap-free: a real alert delivered between save and a successful test goes only to the unverified replacement, and once saved, the **Current:** line only ever shows the masked value — the old URL is unrecoverable from the dashboard. Before you start, copy the current webhook URL somewhere safe; it's your only way back if the new one fails. Then: create the replacement webhook in Slack, paste it into the recipient, save, and **Send test** it immediately. If the test fails or is rate-limited (see [Plan limits](#plan-limits)), paste the retained old URL back in and save to restore delivery before troubleshooting further. Only revoke the old webhook in Slack's Incoming Webhooks settings once the test against the new URL succeeds.
## Do the same through the API or MCP
Read the webhook URL with a silent prompt instead of writing it into the command — a URL typed directly into `-d` lands in your shell history and is visible to other users on the box via `ps` while `curl` runs:
```bash
read -rsp 'Slack webhook URL: ' SLACK_WEBHOOK_URL; echo
printf '%s' "$SLACK_WEBHOOK_URL" | jq -Rs '{
name: "on-call-slack",
type: "slack",
config: {url: .},
events: ["down", "up", "flapping"]
}' | curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
```
The response masks the URL — `config.url` never comes back in plaintext after creation:
```json
{
"id": 51,
"name": "on-call-slack",
"type": "slack",
"config": {"url": "https://hooks.slack.com/services/T00000000/B00000000/********"},
"default": false,
"status": "active",
"events": ["down", "up", "flapping"],
"monitor_ids": [],
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}
```
Verify delivery before relying on the recipient:
```bash
curl -X POST https://api.monitive.com/api/v1/recipients/51/test \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
```json
{"recipient_id": 51, "type": "slack", "status": "delivered", "response_code": 200}
```
**Rotating the URL.** There's no separate rotate endpoint — `PATCH` the recipient with a new `config.url`. `PATCH` performs the cutover immediately: as soon as it succeeds, the recipient's live webhook is the new URL, before anything has confirmed Slack will accept it. This sequence is not gap-free — between a successful `PATCH` and a successful `POST .../test`, a real alert delivers only to the unverified replacement, and if that test fails or is blocked by the 1-per-minute test rate limit (see [Plan limits](#plan-limits)), `GET` only ever returns the masked URL, so the old webhook can't be recovered unless you retained its plaintext value yourself.
Before rotating, save the current plaintext URL somewhere safe — it's your only way back if the new one doesn't work, since um-api never returns a stored webhook URL in plaintext again. Create the replacement webhook in Slack, then test it directly against Slack, bypassing um-api, to confirm Slack accepts it before the recipient's live URL changes:
```bash
curl -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' -d '{"text": "test"}'
```
A `200` response with body `ok` means Slack accepts the new URL. Only then `PATCH` the recipient:
```bash
read -rsp 'New Slack webhook URL: ' SLACK_WEBHOOK_URL; echo
printf '%s' "$SLACK_WEBHOOK_URL" | jq -Rs '{config: {url: .}}' \
| curl -X PATCH https://api.monitive.com/api/v1/recipients/51 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
```
A `PATCH` that only sends `name`, `events`, or `default` leaves the stored URL untouched. A `PATCH` whose `config` omits both `url` and `channel` fails with `config must set url or channel`. Sending the masked value back (the `********` you'd copy from a `GET` or from the app's "Current:" line) fails too — see [Troubleshooting](#troubleshooting).
`POST /api/v1/recipients/51/test` the recipient the same way as [Verify delivery](#do-the-same-through-the-api-or-mcp) above. If it fails, `PATCH` the retained old URL back immediately to restore delivery before troubleshooting further — only revoke the old webhook in Slack once the new URL's test succeeds. A `PATCH` that succeeds only proves um-api accepted the URL's shape, not that Slack will accept deliveries to it.
Attach the recipient to a monitor the same way as any other recipient type — through `PUT /api/v1/monitors/{monitorID}/recipients`, or at creation time via `create_monitor`'s `recipient_ids`/`recipients` arguments — see [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp).
Through MCP, `create_monitor`'s `recipients` argument can attach an existing Slack recipient by id at monitor-creation time; creating the Slack recipient itself has no MCP tool today — use the REST API or the dashboard for that.
## Plan limits
- **Webhook URL length:** up to 2048 characters (`maxSlackURLLen` in um-api's `internal/webhook/slack.go`).
- **Channel override length:** optional `config.channel`, `#` or `@` followed by 1–80 characters with no whitespace or control characters (`slackChannelShapeRe`/`validateSlackChannel` in um-api's `internal/api/recipients.go`). This is a legacy, API-only option for webhooks that still allow a channel override — most webhooks route to the channel you picked when you created them in Slack, so pick the right channel there instead of relying on `config.channel`.
- **Test send rate:** 1 request per minute per recipient (`recipientTestLimiter` in um-api's `cmd/dispatcher/main.go`). Going over it returns `429` with a `Retry-After` header; the app shows "Wait Ns before testing …".
See [Choose who gets alerts](/docs/guides/alert-recipients/) for the recipient name length limit (255 bytes) shared by every recipient type.
## Troubleshooting
**A real alert or test send fails with `no_service`.** Slack returns `no_service` when the webhook has been removed, or the Slack app it belongs to was uninstalled or had its webhook revoked. Create a new webhook in Slack and `PATCH` the recipient's `config.url` to the new value — there's no way to reactivate the old URL. A `no_service` response is a terminal 4xx: um-api does not retry it, for a test send or a real alert.
**A real alert fails with a different Slack 4xx error, like `invalid_token`, `channel_not_found`, or `channel_is_archived`.** These are examples of the error strings Slack's own incoming-webhooks docs describe, not an exhaustive list — um-api passes Slack's response body through unchanged. Any non-2xx response other than a transport error, `429`, or `5xx` fails the delivery immediately with no retry, the same as `no_service` above.
**Creating or updating the recipient returns `400` with `config.url must be a Slack incoming webhook URL (https://hooks.slack.com/services/{team}/{bot}/{token})`.** The most common cause is pasting the masked value shown by `GET` or by the app's "Current:" line — the `********` suffix doesn't parse as a real webhook URL. Paste the real URL from Slack, not a masked one.
**The same `400` shows up for a URL that isn't `hooks.slack.com`.** A Slack Workflow Builder URL, a `/triggers/` webhook, or any other Slack URL that isn't the classic `https://hooks.slack.com/services/{team}/{bot}/{token}` shape fails the same validation — Slack recipients only accept an incoming-webhook URL in that exact form.
**Send test returns `429`.** You've hit the 1-request-per-minute test limit for that recipient (see [Plan limits](#plan-limits)). Wait for the `Retry-After` header's duration and try again — this limit only applies to **Send test**, not to real alert delivery.
**Send test returns `502` with `status: "failed"`.** That's a transport error reaching Slack — the request to `hooks.slack.com` itself failed, rather than Slack responding with an error. Unlike a real alert, a test is never retried: it reports this result once and stops. A real alert that hits the same kind of transport error, or a `429` or `5xx` from Slack, does go through the normal retry schedule — only a Slack-side 4xx like `no_service` fails a real alert immediately.
**Send test returns `error: "invalid stored Slack URL"`.** The URL currently stored on the recipient no longer parses as a valid Slack webhook URL. `PATCH` the recipient with a fresh, valid `config.url` from Slack.
---
# Send alerts to PagerDuty
> Create a PagerDuty recipient, test it, rotate its integration key, and understand the down/flapping/up to trigger/resolve mapping.
## What it does
A PagerDuty recipient sends outage and recovery alerts straight to a PagerDuty service through its native Events API v2 — no relay, and no confirmation step: it's `active` as soon as you create it. Unlike an email recipient, there's nothing to confirm before alerts start.
Each monitor event becomes a specific Events API v2 action:
| Event | Action | Severity |
|---|---|---|
| `down` | trigger | `error` |
| `flapping` | trigger, same incident | `warning` |
| `up` | resolve | — |
A `down` or `flapping` event opens or continues one PagerDuty incident per outage — the dedup key is `-`, for example `k7q2mx-14-7`, so a `flapping` trigger lands on the same incident a prior `down` opened, and a new outage on the same monitor always opens a new incident. The `up` resolve closes it. A delivery retries only on a transport error, a `429`, or a `5xx` from PagerDuty; anything else is terminal on the first attempt.
If you route PagerDuty Event Orchestration rules on the event's `custom_details`, match on `custom_details.monitor_ref` — it replaces the old `custom_details.monitor_id`. An incident that opened under the old dedup key before this change won't auto-resolve; resolve it by hand in PagerDuty.
## Set it up in the app
In PagerDuty:
1. Open the service you want alerts to land in.
2. Go to **Integrations** and add **Events API v2**.
3. Copy the integration key it generates.
In the Monitive dashboard:
1. Go to **Recipients** and click **Add recipient**.
2. Choose **PagerDuty**, enter a **Name**, paste the **Integration key**, pick which events to notify on, and optionally turn on **Default for new monitors**.

3. Click **Create recipient**. There's no confirmation step — the recipient is active immediately.
4. Click **Send test**. A successful test shows "Test accepted by PagerDuty for ``" — see [Troubleshooting](#troubleshooting) for what "accepted" does and doesn't guarantee.
5. Attach the recipient to monitors from each monitor's **Recipients** section, the same way you would any other recipient type — see [Choose who gets alerts](/docs/guides/alert-recipients/).
### Rotate the integration key
To rotate the key, change it on the recipient you already have. Editing the key in place keeps the recipient's monitor attachments, its `default` setting, and its `events`, so there's nothing to copy to a second recipient.
1. In PagerDuty, add a replacement Events API v2 integration on the same service, or on the service you're moving alerts to, and copy its key. Keep the old integration until step 4.
2. Swap the key on the recipient. In the dashboard, open the recipient's **Edit** dialog, paste the replacement key into the integration key field, and save. Through the API, `PATCH` the recipient with the replacement key, read with a silent prompt and sent on stdin, as [Do the same through the API or MCP](#do-the-same-through-the-api-or-mcp) shows.
The integration key field in the **Edit** dialog always starts blank, because Monitive never shows a stored key back to you, masked or otherwise, in an editable field. A hint names the last four characters of the stored key, so you can confirm you're changing the right recipient. Saving with the field blank keeps the stored key, and there's no way to clear the key to empty.

3. Click **Send test** on the recipient. The test sends with the key the recipient stores at the moment you click, and Monitive checks only a key's shape when you save it (see [Troubleshooting](#troubleshooting)), so the test is what proves PagerDuty accepts the replacement. If the test fails, copy the old key from its integration in PagerDuty, put it back on the recipient the same way, and investigate. The old key still works because you haven't removed its integration yet.
4. After the test passes, look in PagerDuty for incidents still open under the old integration and resolve them by hand: an `up` event sent with the replacement key can't resolve an incident the old key opened. Then remove the old integration in PagerDuty.
The swap is a cutover, not a gap-free migration. Each key change cancels every alert the recipient has waiting to send or retry, so those alerts don't go out with either key, and an alert a worker has already started sending finishes with the old key. Schedule the swap outside an active incident when you can: an outage whose `down` alert gets cancelled this way, for example one still inside the two-minute grace, doesn't page anyone until the monitor changes state.
## Do the same through the API or MCP
Create a PagerDuty recipient with `POST /api/v1/recipients`. The integration key is a credential — avoid passing it as a `curl` argument, since that both lands it in your shell history and exposes it to other local users through the process list (`ps`) while the command runs. Read it with a silent prompt and pipe it straight into the request body instead:
```bash
read -rsp 'PagerDuty integration key: ' PD_KEY; echo
printf '%s' "$PD_KEY" | jq -Rs --arg name "On-call PagerDuty" \
'{name: $name, type: "pagerduty", config: {integration_key: .}, events: ["down", "up", "flapping"]}' \
| curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
unset PD_KEY
```
The `201` response is `active` immediately and carries no `secret` — a PagerDuty recipient has nothing to reveal once:
```json
{
"id": 42,
"name": "On-call PagerDuty",
"type": "pagerduty",
"config": {"integration_key": "********cdef"},
"default": false,
"status": "active",
"events": ["down", "up", "flapping"],
"monitor_ids": [],
"created_at": "2026-10-20T12:00:00Z",
"updated_at": "2026-10-20T12:00:00Z"
}
```
`config.integration_key` is always masked on the way out — `********` plus the last 4 characters of the stored key, or a bare `********` if the stored value doesn't parse as a valid key. That's true on every read, not just right after creation, so there's no API call that returns the key you sent in full again.
Send a test with `POST /api/v1/recipients/{id}/test`:
```bash
curl -X POST https://api.monitive.com/api/v1/recipients/42/test \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
```json
{
"recipient_id": 42,
"type": "pagerduty",
"status": "accepted",
"response_code": 202,
"message": "PagerDuty accepted the test trigger and resolve. PagerDuty processes events asynchronously, so a test incident can remain open; resolve it in PagerDuty if it does."
}
```
To rotate the key, send the replacement in `PATCH /api/v1/recipients/{id}`, and follow [Rotate the integration key](#rotate-the-integration-key) for the test and cleanup around it. Treat the integration key as a credential: read it with a silent prompt and pipe it into the request body rather than passing it as a `curl` argument, which would otherwise land it in your shell history and expose it to other local users through the process list:
```bash
read -rsp 'Replacement PagerDuty integration key: ' PD_KEY; echo
printf '%s' "$PD_KEY" | jq -Rs '{config: {integration_key: .}}' \
| curl -X PATCH https://api.monitive.com/api/v1/recipients/42 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-
unset PD_KEY
```
Send the real key you want to switch to, never the masked value a prior response returned — see [Troubleshooting](#troubleshooting). `type` is immutable: a `PATCH` that includes `"type"` always returns `400`, even when it matches the recipient's current type.
Through MCP, `create_monitor`'s `recipients` argument can attach an existing PagerDuty recipient by id at monitor-creation time; creating the recipient itself, sending a test, and rotating its key have no MCP tool today — use the REST API or the dashboard for those.
## Plan limits
A PagerDuty recipient's name is capped at 255 bytes, the same limit every recipient type shares — see [Choose who gets alerts](/docs/guides/alert-recipients/#plan-limits).
**Send test** is rate-limited to one request per minute per recipient. A faster retry gets a `429`.
There's no PagerDuty-specific cap on how many PagerDuty recipients an account can create.
## Troubleshooting
**Create or `PATCH` fails with `400` and a routing-key-shaped complaint.** `config.integration_key` must be exactly 32 characters of `[A-Za-z0-9]` — a legacy integration key or a newer orchestration key both match that shape. Anything shorter, longer, or carrying punctuation (including stray whitespace from a copy-paste) is rejected before anything is dispatched to PagerDuty.
**`PATCH`ing the masked value back returns `400`.** The `config.integration_key` a `GET` or the dashboard shows you is always masked — `*` isn't a character a real PagerDuty key uses, so resending that string is rejected as an invalid key, not silently ignored. Omit `config` from the `PATCH` body entirely to keep the existing key; the dashboard's edit dialog does this for you whenever you leave the key field blank.
**A test left an incident open in PagerDuty.** A successful test response means PagerDuty accepted both the trigger and the resolve — two `2xx`s — not that PagerDuty actually closed the incident. The Events API processes events asynchronously, so a test incident can still be open in your PagerDuty service after a successful test. Resolve it there by hand if it is.
**Send test returns `429`.** Test sends are limited to one request per minute per recipient. Wait a minute and retry.
**An outage's incident isn't auto-resolving in PagerDuty.** Check first that `up` is in the recipient's subscribed `events` — a recipient that doesn't subscribe to `up` never reports a recovery, so the incident PagerDuty opened on the `down` or `flapping` trigger stays open until something else closes it. If `up` is subscribed and the incident still isn't closing, note that deleting or detaching the recipient, rotating `config.integration_key`, or disabling the monitor does **not** resolve an incident already open under the old key — only you, in PagerDuty, or PagerDuty's own auto-resolve setting can close it. That's why [Rotate the integration key](#rotate-the-integration-key) has you resolve those incidents by hand before you remove the old integration.
**Never attach a PagerDuty integration key to a `type: "webhook"` recipient.** Monitive's webhook payload isn't the shape PagerDuty's Events API expects, and PagerDuty rejects it outright. Create a native `type: "pagerduty"` recipient instead, through the app or `POST /api/v1/recipients` — it speaks the Events API v2 format directly, with no relay needed.
---
# Maintenance windows
> Set a daily or one-time maintenance window on a monitor so alerts stay silent while checks and incident records keep running.
## What it does
A monitor's maintenance window silences alerts for incidents that open while it's active. Checks keep running on the normal interval, and incidents are still recorded — each one flagged `maintenance: true` on `GET /incidents` (see [Incidents](/docs/incidents/)) if it opened during the window.
What's silenced is the alert, not the incident: no webhook, email, push, or SSE alert goes out for a down or flapping incident that opens inside the window, and its recovery alert is skipped too, but only if every incident that recovery resolves was itself opened during a window. The decision is made once, at the moment an incident opens, with exclusive boundaries at both ends — an incident that opened just before the window started keeps alerting normally. Uptime percentages aren't adjusted for maintenance time either; a down incident during a window still counts against uptime.
## Set it up in the app
1. Open a monitor and click **Edit**, then expand **Advanced**.
2. Set **Maintenance window** to **Every day** or **Once**.
- **Every day** asks for **Start**, **End**, and **Time zone**. It repeats daily in that zone and can span midnight — for example `23:00`–`03:00`.
- **Once** asks for **Starts** and **Ends**, a single absolute span.
3. Click **Save**.

The monitor's detail page shows a **Maintenance** row summarizing the window, for example `Every day 23:00–03:00 (Europe/Lisbon)`, with a second line reading `Active now · ends in 2h 15m`, `Starts in 40m`, or an ended timestamp, depending on where the window currently sits. Any incident that opened during a window carries a muted **Maintenance** badge in the incidents list, with a tooltip reading "Alerts silenced: opened during a maintenance window."

## Do the same through the API or MCP
Set a daily window:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maintenance": {
"type": "daily",
"start_time": "23:00",
"end_time": "03:00",
"timezone": "Europe/Lisbon"
}
}'
```
Or a one-time window, using any RFC3339 offset:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maintenance": {
"type": "once",
"starts_at": "2026-11-01T09:00:00+01:00",
"ends_at": "2026-11-01T11:00:00+01:00"
}
}'
```
The response echoes both timestamps normalized to UTC, regardless of the offset you sent:
```json
{
"monitor": {
"maintenance": {
"type": "once",
"starts_at": "2026-11-01T08:00:00Z",
"ends_at": "2026-11-01T10:00:00Z"
}
}
}
```
The dashboard (see the screenshot above) displays `once` times in your browser's local time zone, while the API always stores and returns UTC regardless of the offset you sent — don't expect the clock times shown in the app to match a `once` window's UTC values byte-for-byte.
Clear a window back to none:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"maintenance": {"type": "none"}}'
```
Omitting `maintenance` entirely from a `PUT` leaves the stored window unchanged — it isn't the same as clearing it. `POST /api/v1/monitors` without a `maintenance` field creates the monitor with `{"type":"none"}`. See [Monitors](/docs/monitors/) for the full create/update reference.
Through MCP, both `create_monitor` and `update_monitor` take the same `maintenance` object — ask your agent to put a monitor into maintenance and give it the type and times, and it maps directly to this shape. See [Use Monitive through MCP](/docs/mcp/).
## Plan limits
A monitor has exactly one maintenance window — there's no way to stack several windows on the same monitor (`Maintenance` is a single field on `models.Monitor`, not a list). For a daily window, the time zone must be a real IANA name: an empty string, `Local`, or anything `time.LoadLocation` can't resolve is rejected (`validateMaintenanceTimezone` in um-api's `internal/api/maintenance.go`).
See [Monitors](/docs/monitors/) for the monitor limits a maintenance window shares with every other monitor setting, such as monitor count caps and the 60-second minimum check interval.
## Troubleshooting
**"not allowed for type ..."** You sent a field that doesn't belong to the window's `type` — for example `timezone` on a `once` window, or `starts_at` on a `daily` one. Each type accepts only its own fields.
**"unknown time zone ..."** The `timezone` value isn't a real IANA zone name. `Local` and an empty string are both rejected outright, along with anything `time.LoadLocation` can't resolve.
**"end_time: must differ from start_time"** A daily window's `start_time` and `end_time` must differ. Use the midnight-spanning form (for example `23:00`–`03:00`) instead of setting them equal.
**"ends_at: must be after starts_at"** A `once` window's `ends_at` must come strictly after `starts_at`. Two timestamps that differ by less than a microsecond are treated as equal and rejected the same way, since that's PostgreSQL's `timestamptz` precision.
**"maintenance must not be null"** You sent `"maintenance": null` for the whole field. Omit the field entirely instead — on `PUT` that leaves the stored window unchanged, and on `POST` it defaults to `{"type":"none"}`.
**"maintenance.``: must not be null"** You sent `null` for a field inside the `maintenance` object, for example `"start_time": null`. Every field a given type requires must be a real value.
**I still got an alert during the window.** The silencing decision is made once, when the incident opens. If the incident opened just before the window started, it alerts normally even though the window became active moments later — the window's boundary is exclusive, so the start instant itself doesn't count as inside it.
**An old incident is still silent after the window ended.** Expected. Once an incident is flagged as having opened during maintenance, it stays silent through to its recovery alert even after the window ends, including across a down-to-flapping handoff.
**Uptime still dropped during the window.** Expected. A maintenance window only silences alerts — it doesn't adjust uptime. A down incident during a window counts against uptime the same as any other.
---
# Status page
> Turn on a monitor's free public status page from the dashboard or the API.
## What it does
Turning on a monitor's status page publishes one read-only page at `https://status.monitive.com/sp_…`, a public URL that needs no login. The page shows:
- The current status (up, down, flapping, paused, or unknown), when the monitor was last checked, and, while it's down, how long it has been down.
- A 30-day grid of daily uptime percentages. It uses the same calculation as `GET /api/v1/monitors/{id}/uptime`, served from a cached snapshot that can run up to about 70 seconds behind (see [Plan limits](#plan-limits)). A day before the monitor existed reads "Not monitored yet," never a made-up percentage.
- The 30-day average uptime and response time, and a downtime history.

The same page has RSS, Atom, and JSON siblings at `/feed.rss`, `/feed.atom`, and `/status.json` under the same token, plus an SVG badge at `/badge.svg`. To show that badge in a README or on your own site, see [Uptime badge](/docs/guides/uptime-badge/).
The page carries no authentication, and search engines can index it. The unguessable token in the URL is the only thing keeping it unlisted; it isn't a lock. Read the caution in [Set it up in the app](#set-it-up-in-the-app) before you publish one.
Pausing the monitor doesn't unpublish the page. It keeps serving, with a paused headline. To revoke the URL, turn the status page off.
## Set it up in the app
:::caution
This page has no login, and search engines can index it. It publishes the monitor's name, its host, its current status and check times, the last 30 days of daily uptime, the 30-day averages, and up to 50 incident lines. It does **not** publish the monitor URL's path or query string, request headers, or the request body. Anyone you share the page URL with, and anyone who sees an embedded [uptime badge](/docs/guides/uptime-badge/), can reach the page.
:::
1. Open the monitor's detail page and find the **Status page** section.
2. Turn on the **Public status page** switch. Its label changes from **Private** to **Public**.
3. Copy the URL with the copy button, or click **Open** to view the page.

Turning the switch off opens a **Turn off the status page?** confirmation. It explains that the old URL can stay reachable for about 70 seconds while an already-admitted build finishes and caches expire, and that turning the page back on mints a different URL.
## Do the same through the API or MCP
Turn the page on:
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287/status-page \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
```
```json
{"enabled": true, "url": "https://status.monitive.com/sp_0123456789abcdef0123456789abcdef"}
```
Read the switch state the same way, with no body:
```bash
curl https://api.monitive.com/api/v1/monitors/1287/status-page \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
`url` is `null` when the page is off. Once you have the URL, from the dashboard's copy button or from this response's `url` field, assign it to a shell variable instead of pasting it straight into a command:
```bash
PAGE_URL='https://status.monitive.com/sp_0123456789abcdef0123456789abcdef'
```
Replace that value with your own page's URL. The public routes take no `Authorization` header:
```bash
curl "$PAGE_URL/status.json"
```
To build the badge URL and its embed snippets from the same page URL, see [Uptime badge](/docs/guides/uptime-badge/).
There's no MCP tool for this switch. Turn a status page on or off through the REST calls in this section or the dashboard. See [Monitors](/docs/monitors/) and [Feeds](/docs/feeds/) for the monitor and feed-token references this pairs with.
## Plan limits
- One status page per monitor. The free product doesn't offer multi-monitor or branded pages.
- The page, its feeds, and `status.json` cover a trailing 30-day window, the same window the uptime API uses.
- The downtime history and feeds project at most 50 entries, newest first. The 30-day uptime math still accounts for every incident that overlaps the window; only the projected list is capped.
- The origin caches a built page for 60 seconds once the live status agrees with the open incident rows, or 5 seconds while it doesn't. See [Troubleshooting](#troubleshooting) for what "doesn't agree" means in practice. A build can run up to 10 seconds before its result is cached, so the data behind any one response can be up to about 70 seconds old for a settled page, or about 15 seconds for an unsettled one.
- Turning the page off revokes the token at the origin for anything that asks afterward. A build already in flight when you flip the switch can still finish and get served, and the result can stay cached, so the old URL can keep answering for roughly that same 70 seconds.
- Turning the switch on or off requires the account owner role; reading the switch state only requires viewer.
- See [Monitors](/docs/monitors/) for the monitor count and other shared account limits.
## Troubleshooting
**The URL returns `404`.** The page is off, the monitor was deleted, the account is suspended, or the token is malformed. A paused monitor does not cause this: pausing leaves the page public with a paused status.
**`curl -I`, or any non-GET request, returns `404` even though the page loads in a browser.** The status host's routes are GET-only. `HEAD`, `POST`, `PUT`, and `DELETE` all get the same `404` by design, so a method probe can't distinguish "doesn't exist" from "wrong verb." Check with a GET instead:
```bash
PAGE_URL='https://status.monitive.com/sp_0123456789abcdef0123456789abcdef'
curl -s -o /dev/null -w '%{http_code}\n' "$PAGE_URL"
```
**`503` with a `Retry-After: 5` header.** A page build hit its time limit. Retry after the advertised delay. Don't turn the page off and back on to fix it: that mints a different URL and breaks every embedded badge.
**`500`.** A service failure, not a problem with your token. Retry later; there's nothing to rotate.
**The page is still public after I paused the monitor.** By design: pausing doesn't unpublish anything. Turn the status page off instead.
**The page shows up in search results.** Also by design: the free status page isn't marked `noindex`. Turning the status page off revokes the URL, and turning it back on mints a different one.
**The page still loads for a bit after I turned it off.** That's the cache tail described in [Plan limits](#plan-limits): up to about 70 seconds at the origin.
**The public page's numbers lag the dashboard or the uptime API.** They share the same calculation, but the public page serves a cached snapshot that can be up to about 70 seconds old for a settled page, or about 15 seconds while it's unsettled (see [Plan limits](#plan-limits)). A page stays unsettled for as long as its live status disagrees with the open incident rows, or while the status is still unknown, not only during a brief transition. The response's `Age` header counts from when that snapshot was cached, so it understates the data's real age by however long the build itself took.
**`400 enabled is required`, `400 enabled is the only allowed field`, `401`, `403`, or `415`.** The `PUT` body must be exactly `{"enabled": }`. A missing or non-boolean `enabled`, or any other key, is `400`. `401` means a missing or invalid `Authorization` header. `403` means the caller isn't the account owner. `415` means the request is missing `Content-Type: application/json`.
**The dashboard shows "URL unavailable."** The switch is on, but the API didn't return a usable URL. That points to a server-side configuration problem, not something you can fix from the dashboard.
---
# Uptime badge
> Embed a monitor's live uptime badge in a README, a forum post, or your own site.
## What it does
Every public [status page](/docs/guides/free-status-page/) has an SVG badge at `/badge.svg` under the page's URL. The badge reads **uptime** on the left and the monitor's 30-day uptime and current status on the right, for example `99.97% · up`. The right half is green while the monitor is up, red while it's down, amber while it's flapping, and gray while it's paused or its status is unknown. A monitor with no uptime data yet reads `no data` in place of the percentage.
The page's embed snippets wrap the badge in a link back to the status page, so a click on the badge opens the full page. The badge renders anywhere an image does: a README, a forum signature, or your own site's footer.

The badge belongs to the status page. It exists only while the monitor's status page is on, and its URL carries the same token as the page URL.
## Set it up in the app
:::caution
The badge URL contains the status page's token, so embedding the badge on a public site shares the page URL with that site, its visitors, any image proxy in front of it, and crawlers. Treat it the same way you'd treat sharing the page link itself. The [Status page](/docs/guides/free-status-page/#set-it-up-in-the-app) guide lists what the page publishes.
:::
1. Turn on the monitor's status page, as described in [Status page](/docs/guides/free-status-page/#set-it-up-in-the-app).
2. On the monitor's detail page, in the **Status page** section, click **Open**.
3. On the public page, scroll to **Embed this badge**. It previews the badge on a light and a dark background.
4. Click **Copy** next to the **Markdown**, **HTML**, or **BBCode** snippet, and paste the snippet where you want the badge to show.

The page omits the BBCode snippet when the page URL can't be represented safely in that grammar.
## Do the same through the API or MCP
The badge URL is the status page URL followed by `/badge.svg`. Read the page URL from the API:
```bash
curl https://api.monitive.com/api/v1/monitors/1287/status-page \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
```json
{"enabled": true, "url": "https://status.monitive.com/sp_0123456789abcdef0123456789abcdef"}
```
If `url` is `null`, the page is off. Turn it on first, as described in [Status page](/docs/guides/free-status-page/#do-the-same-through-the-api-or-mcp).
Assign the URL to a shell variable instead of pasting it straight into a command, and replace the value with your own page's URL. The badge route takes no `Authorization` header and returns `image/svg+xml`:
```bash
PAGE_URL='https://status.monitive.com/sp_0123456789abcdef0123456789abcdef'
curl "$PAGE_URL/badge.svg"
```
The page's **Embed this badge** section renders these two snippets for that URL:
```html
```
```markdown
[![Uptime status]()]()
```
There's no MCP tool for the status page switch, and the badge needs none: once the page is on, the badge URL is public.
## Plan limits
- One badge per monitor, tied to its single status page. The badge's label, colors, and text aren't configurable.
- The percentage covers the same trailing 30-day window as the status page and the uptime API.
- The badge comes from the same cached snapshot as the page, so it can be up to about 70 seconds old at the origin. See the status page's [Plan limits](/docs/guides/free-status-page/#plan-limits) for how the cache works. An embedding site or an image proxy can hold the badge longer.
- Turning the status page off revokes the badge along with the page. The old badge URL can keep answering for about 70 seconds at the origin, and longer where an image proxy cached it.
- Turning the status page on or off requires the account owner role.
## Troubleshooting
**The badge shows as a broken image, or its URL returns `404`.** The status page is off, the monitor was deleted, the account is suspended, or the token is malformed. A paused monitor does not cause this: the badge keeps serving with a gray `paused` status. Like the page, the badge route is GET-only, so a `curl -I` probe also returns `404`.
**The badge broke after I turned the page off and back on.** Turning the page back on mints a different token, so the old badge URL is gone. Copy the snippet again from the page.
**The badge and the page briefly disagree.** All formats (page, feeds, JSON, and badge) carry the same data, and the same `Cache-Control` policy, only while they're served from the same cached snapshot. `Age` won't confirm that: it's calculated per response from when each request reached the cache, so it can differ across formats even when they share a snapshot, and an intermediary cache can change it further. A request right before that snapshot expires and another right after can land on different snapshots with no proxy involved.
**The badge in a GitHub README lags the page.** GitHub serves README images through its own image proxy, camo, which can hold the badge longer than the status page's cache does. Other sites that proxy or cache images behave the same way. To see the current number, open the status page.
**`503` with a `Retry-After: 5` header.** A page build hit its time limit. Retry after the advertised delay. Don't turn the page off and back on to fix it: that mints a different URL and breaks every embedded badge.
---
# Report emails
> Turn the weekly and monthly uptime report emails on or off for each account you're in, and see what each report contains, when it arrives, and which address it goes to.
## What it does
Monitive emails each member a weekly and a monthly uptime report for every account they belong to. Reports are separate from outage alerts, which go to the recipients attached to each monitor — see [Send alerts to email](/docs/guides/email-alerts/).
Both reports are on by default for every member of every account. The setting is per person and per account: turning a report off for one team account doesn't change it for any other account you're in, or for anyone else on that team. The unsubscribe link at the bottom of a report changes the same setting as the switch in Settings.
**When each report arrives.** All times are UTC.
- **Weekly** covers the previous ISO week, from Monday 00:00 to the next Monday 00:00 UTC. It's prepared at 07:00 UTC on Monday and sent shortly after.
- **Monthly** covers the previous calendar month. It's prepared at 08:00 UTC on the 1st and sent shortly after.
If a report can't be prepared on time, for example during an outage or because the account didn't qualify yet, preparation is retried until 07:00 UTC on Tuesday for the weekly report, or 08:00 UTC on the 2nd for the monthly one. A copy that hasn't started sending by that cutoff isn't sent. A copy that started sending before the cutoff can still arrive a little after it.
Subjects look like `Monitive weekly report 40 / 2026` and `Monitive monthly report September 2026`.
**Who gets one.** An account's report is prepared only if, at that moment, the account isn't suspended and has at least one enabled monitor that was created before the period ended. When the report is prepared, it lists every member who has that report's switch on and an email address on their user. Turning a switch on after that moment doesn't add you to that period's report. Just before each copy is sent, your switch and your membership are checked again, so your copy is dropped if you turned the switch off or left the account after the report was prepared.
**What a report contains.** Each report is an HTML email with a plain-text alternative:
- A top line naming the period, for example `WEEKLY REPORT · 28 SEP TO 4 OCT 2026`.
- A headline such as `N of M monitors stayed up all week.` (or `all month.` in the monthly report).
- Three figures, each compared with the previous period: uptime, outages with their total downtime, and average response time. A figure shows `N/A` when there's no data to compare.
- **Needs attention**: monitors that had an outage, or whose average response time rose 30% or more compared with the previous period. Each outage shows its start time, its duration, and, when known, a reason such as `HTTP 503`.
- **Down all week** or **Down all month**: monitors that were down for the whole period. Each one shows when it went down, as "Down since …", and a **Pause it** link that opens the monitor in the dashboard. Pausing it there stops both its checks and its alerts; see the `enabled` field in [Monitors](/docs/monitors/). These monitors are left out of the three figures.
- **Everything else**: how many monitors stayed at 100% uptime, with their average, fastest, and slowest response times.
- A **See the full report** button that opens the dashboard. Only the HTML version has it.
- A footer that reads `You get this weekly report because you are a member of the team.`, naming the team by its owner's GitHub username (the sentence is generic when the owner has none). Below it are a **Change report settings** link that opens Settings in the dashboard, and an `Unsubscribe from weekly reports` or `Unsubscribe from monthly reports` link.
This weekly report is for a fictional account with 10 monitors: one had two outages, one got slower, and one was down all week.

**Where reports go.** Reports go to the email address on your signed-in identity — for example, the address you sign in with by email, or one you linked under **Settings → Connected identities**. There's one address per person, so every account's reports go to that same address. If your user has no email address, you get no reports, even with both switches on. The **Report emails** card doesn't warn you about this. To fix it, add an address under **Settings → Connected identities**, as described in [Sign in](/docs/guides/sign-in/).
## Set it up in the app
1. Sign in at [my.monitive.com](https://my.monitive.com). If you belong to several accounts, make sure the account you want to change is the current one — the card names it.
2. Go to **Settings** and find **Report emails**, below **Connected identities**. The card reads "Reports for the `` account. Each account you're in has its own."
3. Turn **Weekly report** or **Monthly report** on or off. The switch moves only after the change is saved, and a toast confirms it, for example "Weekly report turned off."
4. Repeat in each account whose reports you want to change.

**Unsubscribe from an email.** Opening the unsubscribe link in a report shows "Stop sending Weekly uptime report emails for this team? Outage alerts and your other report subscription are not affected." with an **Unsubscribe** button. For a monthly report's link, the page says Monthly. Your mail client's built-in unsubscribe button does the same thing without showing the page. Either way, only that report type turns off, and only for that account — it's the same switch as in Settings. To turn the report back on, use Settings. The card shows an unsubscribe the next time you load Settings.
## Do the same through the API or MCP
There's no API-key or MCP equivalent. The dashboard calls `GET /api/v1/me/reports` and `PATCH /api/v1/me/reports`, and both accept only a signed-in dashboard session. Calling either one with an API key or an MCP/OAuth access token returns `403 {"error":"session_required"}`: an API key is shared across the whole account, so it can't change one person's mail settings. No MCP tool covers reports. See [API keys](/docs/api-keys/) for key details and [Use Monitive through MCP](/docs/mcp/) for the tools that exist.
For reference, both methods return this shape:
```json
{
"account_id": 42,
"weekly": true,
"monthly": false,
"email": "jane@example.com",
"deliverable": true
}
```
`email` is `null` when your user has no address, and `deliverable` is `true` exactly when `email` isn't `null`. `PATCH` takes `weekly`, `monthly`, or both, each a JSON boolean, and only the fields you send change. Any role can read and change their own setting. The request is rejected with `400` and one of these messages:
- `unknown field ""` for any other key.
- `at least one of weekly or monthly is required` for an empty object, `{}`.
- `weekly must be a boolean` or `monthly must be a boolean` for `null`, a string, or a number.
## Plan limits
Reports have no plan limit. They're on by default for every member of every account, and they don't count against the daily cap on email alerts — see [Send alerts to email](/docs/guides/email-alerts/#plan-limits).
**Needs attention** lists up to 25 monitors, with up to 5 outages each. **Down all week** and **Down all month** list up to 25 monitors. Anything beyond a cap is replaced by one line that counts the rest and points you to the dashboard. Each part of the email is also kept under 100 KiB, by dropping the last entries in those lists if needed.
Each report goes to each person at most once per period, and a failed send isn't retried.
## Troubleshooting
**I have a switch on but get no reports.** Check these causes:
- Your user may have no email address. The card doesn't warn about this. Add one under **Settings → Connected identities** — see [Sign in](/docs/guides/sign-in/).
- When the report was prepared, the account may have had no enabled monitor created before the period ended, or it may have been suspended.
- You may have turned the switch on after that period's report was prepared.
**I turned a report on, but this week's (or this month's) didn't arrive.** A report lists its members when it's prepared, normally at 07:00 UTC on Monday or 08:00 UTC on the 1st. A switch turned on after that takes effect from the next period.
**I turned a report off but still got one.** Turning a switch off stops your copy of any report that hasn't started sending yet, including the current period's, because each copy is checked again just before it's sent. A copy that had already started sending when you switched it off can still arrive.
**I unsubscribed from an email, but Settings still shows the switch on.** The card loads once when you open Settings. Reload the page.
**I unsubscribed but still get reports from another team.** Expected. Each account has its own setting. Unsubscribe from that team's email, or switch to that account and turn the report off in Settings.
**"Too many attempts. Try again in Ns."** Wait the number of seconds shown, then try again.
**"Couldn't save report email settings. Try again."** Your change may not have been saved. Check whether the switch moved before you try again. After a network or server error, the card reloads, so the switches show what's actually saved.
**"Couldn't load report email settings." or "Not available yet."** Click **Retry**.
---
# Team members
> Invite teammates by GitHub username, assign roles, change who owns the account, and switch between accounts you belong to.
## What it does
A Monitive account can have more than one member. Each member holds one role — **viewer**, **member**, or **owner** — and roles are cumulative: a member can do everything a viewer can, and an owner everything a member can.
| Role | Can do |
|---|---|
| Viewer | Read monitors, uptime, a monitor's status-page settings and attached recipients, incidents, account-level recipients, webhook deliveries, the account and its usage, announcements, and push subscriptions. Remove themselves from the account. |
| Member | Everything a viewer can, plus: create, update, delete, and test monitors; create, update, delete, and test account-level recipients and resend a recipient's confirmation; attach recipients to a monitor; set or clear a monitor's legacy webhook; subscribe and unsubscribe push endpoints. |
| Owner | Everything a member can, plus: manage API keys; update account settings; read and rotate the feed token; read account events; enable or disable a monitor's public status page; list members, change a member's role, and remove any member; create, list, and revoke invites. |
A handful of routes aren't account-role permissions at all — they depend on who's signed in, not on a role: accepting an invite addressed to you, linking a second sign-in identity, and switching between accounts you belong to. These need a dashboard session and are covered below, not in the table above.
## Set it up in the app

### Invite someone
Only an owner sees **Settings → Team**.
1. Go to **Settings → Team**.
2. Under **Invite a member**, enter their GitHub username and pick a role (**Member**, **Viewer**, or **Owner** — defaults to **Member**).
3. Click **Invite**. The new row appears under **Pending invites**.
Invites are addressed by GitHub username, not email — the invitee must sign in to Monitive with GitHub, or link a GitHub identity to whichever account they already use, before they can accept.
### Accept an invite
If you're signed in with GitHub already, an invite addressed to your GitHub username shows as a banner — "*<account>* invited you as *<role>*" — with an **Accept** button, on every page.
If you signed up with email or Google, link GitHub first: go to **Settings → Connected identities** and click **Add GitHub**. Once linked, the same banner appears and **Accept** joins you to the inviting account. See [Sign in](/docs/guides/sign-in/) for how identity linking behaves when an identity is already linked elsewhere.
### Change a role or remove a member
Under **Members**, an owner can change any row's role with its **Role** select, or click **Remove**, which asks "Remove this member?" before it takes effect.
There's no dashboard action for leaving an account you don't own — **Settings → Team** is owner-only, so a member or viewer who opens it sees "Only account owners can manage the team." To leave, ask an owner to remove you. (The API does support removing yourself; see below.) An owner who wants to leave first makes sure another owner exists on the account.
### Switch accounts
If you belong to more than one account, use the account switcher in the header to move between them.
## Do the same through the API or MCP
**Accepting an invite, linking a GitHub identity, and switching accounts all require a dashboard browser session — none of them work with an API key or an MCP/OAuth access token.** Calling `POST /api/v1/me/account` with a non-session credential returns `422 {"error":"session_required"}`. Invite management and member management, by contrast, work the same with a dashboard session or an owner-level API key.
Invite someone (owner only):
```bash
curl -X POST https://api.monitive.com/api/v1/account/invites \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"github_username": "jdoe-eng", "role": "member"}'
# -> 201 {"id": 4, "github_id": 583231, "github_username": "jdoe-eng",
# "role": "member", "created_at": "...", "expires_at": "..."}
```
List members and pending invites:
```bash
curl https://api.monitive.com/api/v1/account/members \
-H "Authorization: Bearer $MONITIVE_API_KEY"
# -> [{"user_id": 1, "role": "owner", "github_username": "ana-owner", "created_at": "..."},
# {"user_id": 2, "role": "member", "github_username": "jdoe-eng", "created_at": "..."}]
# email appears on a row only when you're an owner looking at another owner's row.
curl https://api.monitive.com/api/v1/account/invites \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
Change a member's role, or remove a member (owner only for anyone but yourself):
```bash
curl -X PATCH https://api.monitive.com/api/v1/account/members/2 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role": "viewer"}'
# -> 204, or 409 {"error":"last_owner"} demoting the sole remaining owner
curl -X DELETE https://api.monitive.com/api/v1/account/members/2 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
# -> 204. Any role can remove itself; removing someone else needs owner (403
# "forbidden" otherwise).
```
This read-then-write pair has no concurrency protection, the same as other account-mutating endpoints — see [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp) for the general pattern. If two owners change the same member's role at once, the second request to land wins silently; re-read the member list after a change to confirm it took.
Revoke a pending invite:
```bash
curl -X DELETE https://api.monitive.com/api/v1/account/invites/4 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
# -> 204, or 404 {"error":"invite_not_found"}
```
**MCP has no team management tools.** MCP covers monitor operations, listing incidents, and account-status reads — see [Use Monitive through MCP](/docs/mcp/). Invite, member, and role management are REST- and dashboard-only.
**The public OpenAPI spec doesn't document the members endpoints yet** (`GET`/`PATCH`/`DELETE /api/v1/account/members...`) — only the invite and `/me` routes are in [the spec](/api-reference). The shapes above are accurate as of this guide's publication; check the live spec for the invite and `/me` routes.
## Plan limits
Monitive doesn't cap the number of members or pending invites on an account. Monitor counts, however, are per account and shared by every member regardless of role — see [Monitors](/docs/monitors/) for those caps.
An invite expires 7 days after it's created; create a new one if it lapses. A GitHub username can be at most 39 characters, using only letters, digits, and single internal hyphens (no leading, trailing, or doubled hyphens) — the same rule GitHub itself enforces on usernames.
## Troubleshooting
**"That isn't a valid GitHub username" / 400 `invalid_github_username`.** The username has to be 1–39 ASCII letters or digits with single internal hyphens only — no leading or trailing hyphen, no doubled hyphens, no spaces. The API doesn't trim surrounding whitespace, so a pasted value with a trailing space fails even if it looks right.
**404 `github_user_not_found`.** GitHub reports no account with that username. GitHub's lookup is case-insensitive, so a capitalization difference isn't the cause — check whether the account exists or was renamed.
**502 `github_error`.** GitHub's API didn't respond as expected. Retry; this isn't something Monitive can control.
**409 `member_exists`.** That GitHub user already belongs to this account.
**409 `invite_exists`.** There's already a live invite for that GitHub user — check **Pending invites** instead of sending another.
**409 `last_owner`** on a role change or removal. You're trying to demote or remove the account's only owner. Promote another member to owner first.
**409 `member_has_api_keys`** when removing a member. That user created (or last rotated) an API key that's still active — only owners create keys, so this usually means a demoted former owner. The key list doesn't show who created each key, so identify theirs by label or key prefix and delete it (or rotate it and wait 5 minutes for the old key to expire) before removing them. If an integration depends on that key, create and verify its replacement first.
**403 `forbidden`** removing a member. Only an owner can remove someone other than themselves.
**422 `session_required`** on `/me/account`, or `403 session_required` on identity linking. You called it with an API key or MCP token. These need a dashboard session — sign in at [my.monitive.com](https://my.monitive.com) and use the account switcher or Settings instead.
---
# Use Monitive through MCP
> Available MCP tools, annotations, auth model, and host-specific setup.
## What is MCP
Model Context Protocol (MCP) lets AI agents interact with external tools. Monitive's MCP server lets any compatible agent create, inspect, and manage monitors using natural language.
## Available tools
| Tool | Description | Read-only |
|------|-------------|-----------|
| `list_monitors` | List all monitors with current status | Yes |
| `get_monitor` | Get monitor details + recent evidence | Yes |
| `create_monitor` | Create a new monitor | No |
| `update_monitor` | Update monitor configuration | No |
| `delete_monitor` | Delete a monitor | No (destructive) |
| `list_incidents` | Query incidents with filtering | Yes |
| `assert_monitor_healthy` | Check if monitor is healthy (for deploy gates) | Yes |
| `get_account_status` | Usage against caps | Yes |
## Tool annotations
| Tool | title | readOnlyHint | destructiveHint | idempotentHint | openWorldHint |
|------|-------|-------------|-----------------|----------------|---------------|
| `list_monitors` | "List Monitors" | `true` | `false` | `false` | `true` |
| `get_monitor` | "Get Monitor" | `true` | `false` | `false` | `true` |
| `list_incidents` | "List Incidents" | `true` | `false` | `false` | `true` |
| `assert_monitor_healthy` | "Assert Monitor Healthy" | `true` | `false` | `false` | `true` |
| `get_account_status` | "Get Account Status" | `true` | `false` | `false` | `true` |
| `create_monitor` | "Create Monitor" | `false` | `true` | `false` | `true` |
| `update_monitor` | "Update Monitor" | `false` | `true` | `false` | `true` |
| `delete_monitor` | "Delete Monitor" | `false` | `true` | `true` | `true` |
`openWorldHint: true` reflects that all tools make external API calls. `idempotentHint: true` is set only on `delete_monitor` — repeating the call after the monitor is gone produces the same result.
`get_monitor`, `update_monitor`, `delete_monitor`, and `assert_monitor_healthy` take a `monitor_ref` argument (e.g. `"k7q2mx-14"`), and `list_incidents` accepts one as an optional filter — none of these tools take a numeric `monitor_id`. Every tool result that embeds a monitor or incident object carries `ref` (and `number`) instead of a numeric `id`.
## Auth model
The MCP endpoint accepts Bearer credentials: API keys, session tokens, and OAuth access tokens. Which credential you configure depends on the host.
OAuth-based connector hosts such as Claude.ai, Claude Desktop, and ChatGPT should use the OAuth flow when prompted. Config-file and API clients such as Claude Code, Cursor, and the OpenAI API can pass an OAuth access token or a custom `Authorization` header when the host supports custom headers.
OAuth 2.1 discovery endpoints are published at [`https://api.monitive.com/.well-known/oauth-authorization-server`](https://api.monitive.com/.well-known/oauth-authorization-server) (authorization server metadata) and [`https://api.monitive.com/.well-known/oauth-protected-resource/mcp`](https://api.monitive.com/.well-known/oauth-protected-resource/mcp) (protected resource metadata for the MCP endpoint).
For API-key setups, use the same key as the REST API:
```
Authorization: Bearer mk_live_...
```
Create a dedicated key labeled `mcp` for API-key based agent setups.
## Example
```text
User:
Create a monitor for https://example.com/healthz
and tell me whether it is healthy right now.
Agent:
I'll create the monitor and check its status.
Tool: create_monitor
Result: Monitor created (ref: k7q2mx-14, name: "example-healthz")
Tool: assert_monitor_healthy
Result: Healthy — EU, 200, ttfb 184ms
```
## Discovery
Monitive's MCP server is listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers/com.uptimemonitoring/mcp) under `com.uptimemonitoring/mcp`. MCP-aware tools that auto-discover servers from the registry can install it without any manual configuration; the registry entry carries the canonical transport, endpoint, and auth metadata.
## Host compatibility
Manually maintained pre-release — [open an issue](https://github.com/monitive/web/issues) if your host should be listed.
| Host | Transport | Auth | Status |
|------|-----------|------|--------|
| [Claude.ai](#claudeai) | Remote MCP connector | OAuth | ✅ |
| [Claude Desktop](#claude-desktop) | Remote MCP connector | OAuth | ✅ |
| [Claude Code](/docs/connect-claude-code/) | Remote MCP HTTP | OAuth / Bearer header | ✅ |
| [ChatGPT](/docs/connect-chatgpt/) | Custom MCP connector | OAuth | ✅ |
| [Cursor](/docs/connect-cursor/) | MCP config | OAuth / Bearer header | ✅ |
| [OpenAI API](/docs/connect-openai-api/) | Responses MCP | OAuth token / custom headers | ✅ |
*Last verified: 2026-05-26.*
## Listed in registries
- ⏳ [GitHub MCP Registry](https://github.com/mcp) — submission pending 2026-05-19 (#26)
- ⏳ [Official MCP Registry](https://registry.modelcontextprotocol.io) — `server.json` shipped 2026-05-19 (#25), external submission PR pending
## Support
Questions or issues with the MCP server? Email [hello@monitive.com](mailto:hello@monitive.com).
## Host-specific setup
### Claude.ai
In Claude.ai, open **Customize → Connectors**, add a custom connector, and enter:
```text
https://api.monitive.com/mcp
```
Complete the OAuth flow when Claude prompts you to connect your Monitive account.
### Claude Desktop
In Claude Desktop, add Monitive through **Settings → Connectors** as a custom remote MCP connector:
```text
https://api.monitive.com/mcp
```
Complete the OAuth flow when Claude prompts you to connect your Monitive account. Remote MCP servers in Claude Desktop should be added through Connectors, not `claude_desktop_config.json`.
### Claude Code
OAuth or Bearer header via `claude mcp add`. Full install steps, verification, and common errors: [Connect Claude Code](/docs/connect-claude-code/).
### ChatGPT
OAuth via the ChatGPT connector UI — add Monitive as a custom MCP connector. Full install steps, verification, and common errors: [Connect ChatGPT](/docs/connect-chatgpt/).
### Cursor
Bearer header or OAuth via `mcp.json`. Full install steps, verification, and common errors: [Connect Cursor](/docs/connect-cursor/).
### OpenAI API
MCP tool in Responses API calls, API key or OAuth token. Full install steps, verification, and common errors: [Connect via OpenAI API](/docs/connect-openai-api/).
---
# Connect Claude Code
> Add the Monitive MCP server to Claude Code with one shell command.
## Prerequisites
- Claude Code installed (current stable)
- A Monitive account (sign in with GitHub at [my.monitive.com](https://my.monitive.com))
- (Only for the API-key alternative below) an `mk_live_` key — see [API keys](/docs/api-keys/)
## Connect
Add the Monitive remote HTTP MCP server:
```bash
claude mcp add --transport http monitive https://api.monitive.com/mcp
```
Then in Claude Code run `/mcp` — Claude Code opens your browser to authorize via GitHub and stores the access token automatically. No key to manage or paste.
### Alternative: API key CI / headless / automation
Use this in non-interactive environments where a browser OAuth flow isn't possible. The same `mk_live_` key also powers the REST API and the `assert-healthy` GitHub Action.
```bash
claude mcp add --transport http monitive https://api.monitive.com/mcp \
--header "Authorization: Bearer mk_live_..."
```
Replace `mk_live_...` with your actual API key.
## Verify
In Claude Code, type `/mcp` and confirm `monitive` appears with status **connected**. Then ask:
> list my monitors
You should see a tool call to `list_monitors` and a list of your monitors (or an empty result if you don't have any yet).
## Common errors
| Symptom | Cause | Fix |
|---------|-------|-----|
| `401 Unauthorized` (API-key method) | Key is wrong, missing, or not `mk_live_`-prefixed | Confirm the key from [API keys](/docs/api-keys/#api-key-format) starts with `mk_live_` and is pasted in full |
| Browser didn't open / auth didn't finish | OAuth flow was interrupted | Re-run `/mcp` in Claude Code; it re-initiates the OAuth flow |
| Tools missing after `/mcp` | MCP server registered but Claude Code hasn't reloaded | Restart Claude Code fully |
| Connection refused / DNS error | Wrong host in the server URL | The endpoint is `https://api.monitive.com/mcp`, not the marketing host |
## See also
- [MCP reference and host compatibility matrix](/docs/mcp/)
- [Connect ChatGPT](/docs/connect-chatgpt/)
- [Connect Cursor](/docs/connect-cursor/)
- [Connect via OpenAI API](/docs/connect-openai-api/)
- [Connect via REST API](/docs/connect-rest-api/)
---
# Connect ChatGPT
> Add the Monitive MCP server as a custom connector in ChatGPT.
## Prerequisites
- A ChatGPT plan that allows adding custom MCP connectors
- A Monitive account — sign in at [my.monitive.com](https://my.monitive.com)
## Connect
Monitive is listed on the ChatGPT app store — search for it in ChatGPT's connector picker, or install manually:
1. In ChatGPT, open **Settings → Connectors**.
2. Add a custom connector and enter the remote MCP URL:
```text
https://api.monitive.com/mcp
```
3. Complete the OAuth flow when ChatGPT prompts you to connect your Monitive account.
ChatGPT uses OAuth exclusively for custom connectors — you cannot pass a custom `Authorization` header via the connector UI. If you need API-key access from a backend agent, use the [OpenAI API path](/docs/connect-openai-api/) instead.
If you need full MCP tool access while testing prerelease tool changes, enable **Developer Mode** in ChatGPT before adding the connector.
## Verify
In a new ChatGPT chat with the connector enabled, ask:
> list my monitors
You should see the connector invoked and a list returned.
## Common errors
| Symptom | Cause | Fix |
|---------|-------|-----|
| OAuth window never opens | Popup blocker | Allow popups for chatgpt.com and retry |
| Connector visible but tools missing | Developer Mode not enabled | Enable Developer Mode in ChatGPT settings, then reconnect |
| Wrong account authenticated | Different Monitive account in the OAuth tab | Sign out of Monitive in the browser tab, sign in with the correct account, then redo the OAuth flow |
## See also
- [MCP reference and host compatibility matrix](/docs/mcp/)
- [Connect Claude Code](/docs/connect-claude-code/)
- [Connect Cursor](/docs/connect-cursor/)
- [Connect via OpenAI API](/docs/connect-openai-api/)
- [Connect via REST API](/docs/connect-rest-api/)
---
# Connect Cursor
> Add the Monitive MCP server to Cursor with OAuth or an API key.
## Prerequisites
- Cursor stable release
- A Monitive account
- For API-key authentication, an `mk_live_` key from [my.monitive.com](https://my.monitive.com) — see [API keys](/docs/api-keys/)
## Connect
Create or open your Cursor MCP config file and add the Monitive server block:
- **Global (all projects):** `~/.cursor/mcp.json`
- **Project-local:** `./.cursor/mcp.json` in your project root
```json
{
"mcpServers": {
"monitive": {
"url": "https://api.monitive.com/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
Replace `mk_live_...` with your API key. Before you save a project-local configuration, add `.cursor/mcp.json` to `.gitignore`. Don't commit a live API key.
### OAuth alternative
Cursor supports OAuth for remote MCP servers that publish OAuth metadata. To use OAuth instead of an API key, omit the `headers` field:
```json
{
"mcpServers": {
"monitive": {
"url": "https://api.monitive.com/mcp"
}
}
}
```
When Cursor prompts you, complete the browser flow to authorize your Monitive account.
## Verify
Close all Cursor windows and background processes, and then relaunch Cursor. Open the MCP panel and confirm that `monitive` appears as connected with eight tools.
To verify the integration end to end:
1. Ask Cursor to list your monitors:
> List my monitors.
Cursor calls `list_monitors` and returns your monitors or an empty result.
2. Ask Cursor to create a test monitor:
> Create a monitor for `https://example.com/healthz` named `cursor-test`.
Cursor calls `create_monitor` and returns a monitor with a `ref`. If a monitor for that URL already exists, the API returns `409 Conflict`. Delete the existing monitor or use a different URL.
3. Ask Cursor to delete the test monitor:
> Delete the `cursor-test` monitor.
Cursor calls `delete_monitor` and asks for confirmation because the tool has `destructiveHint: true`. Confirm the deletion. Monitive permanently deletes the monitor and its incident history.
## Common errors
| Symptom | Cause | Fix |
|---------|-------|-----|
| `401 Unauthorized` | Missing or incorrect key | Confirm the key starts with `mk_live_` and is pasted in full without extra whitespace |
| Server not appearing | Config file in wrong location | Cursor reads only `~/.cursor/mcp.json` or `./.cursor/mcp.json` |
| Tools not appearing after config change | Cursor not fully restarted | Quit Cursor fully (including background helper) and relaunch |
| Destructive tool blocked | Cursor is waiting for confirmation before it runs `delete_monitor` | Confirm the action in Cursor |
| `409 Conflict` on create | A monitor for that URL already exists | Delete the duplicate monitor by `ref`, or use a different URL |
## See also
- [MCP reference and host compatibility matrix](/docs/mcp/)
- [API keys](/docs/api-keys/)
- [API reference](/api-reference/)
- [Connect Claude Code](/docs/connect-claude-code/)
- [Connect ChatGPT](/docs/connect-chatgpt/)
- [Connect via OpenAI API](/docs/connect-openai-api/)
- [Connect via REST API](/docs/connect-rest-api/)
---
# Connect via OpenAI API
> Use the Monitive MCP server in your OpenAI Responses API requests.
## Prerequisites
- An OpenAI API account with Responses API access
- An `mk_live_` API key from [my.monitive.com](https://my.monitive.com) — see [API keys](/docs/api-keys/)
## Connect
Use the `mcp` tool type in a Responses API request. This example restricts `allowed_tools` to the read-only `list_monitors` for safe verification — remove the restriction to enable write tools in production:
```bash
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"tools": [
{
"type": "mcp",
"server_label": "monitive",
"server_url": "https://api.monitive.com/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
},
"allowed_tools": ["list_monitors"]
}
],
"input": "List my Monitive monitors."
}'
```
Replace `mk_live_...` with your Monitive API key. Keep the two keys separate: `OPENAI_API_KEY` (`sk-...`) is your OpenAI credential; `mk_live_...` is your Monitive credential.
### Auth modes
| Use case | Method |
|----------|--------|
| Backend-to-backend / server agent | Pass `Authorization: Bearer mk_live_...` in the `headers` field (shown above) |
| User-facing agent with OAuth | Pass the user's OAuth access token via the `authorization` field of the MCP tool config instead of `headers.Authorization` |
To enable write tools (`create_monitor`, `update_monitor`, `delete_monitor`) in production, remove `allowed_tools` and handle the `mcp_approval_request` events in the response stream, or set `require_approval: "never"` only after confirming user intent in your application layer.
## Verify
Run the curl call above. The response should include a tool call to `list_monitors` and a follow-up assistant message summarising your monitors.
## Common errors
| Symptom | Cause | Fix |
|---------|-------|-----|
| `401` from Monitive | Wrong key in `headers.Authorization` | Confirm the key starts with `mk_live_` — do not use your OpenAI key here |
| MCP tool ignored by model | Older model version without `mcp` tool support | Switch to `gpt-4o` or a later model |
| Server not found | URL typo | The endpoint is `https://api.monitive.com/mcp`, not `api.monitive.com` |
## See also
- [MCP reference and host compatibility matrix](/docs/mcp/)
- [Connect Claude Code](/docs/connect-claude-code/)
- [Connect ChatGPT](/docs/connect-chatgpt/)
- [Connect Cursor](/docs/connect-cursor/)
- [Connect via REST API](/docs/connect-rest-api/)
---
# Connect via REST API
> Make your first Monitive REST API call with curl and an API key.
## Prerequisites
- An `mk_live_` API key from [my.monitive.com](https://my.monitive.com) — see [API keys](/docs/api-keys/)
- `curl` (any recent version)
## Make your first call
List your monitors:
```bash
curl https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer mk_live_..."
```
The API's address is `https://api.monitive.com`.
Replace `mk_live_...` with your actual API key.
## Create a monitor
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer mk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "my-api",
"url": "https://example.com/healthz",
"type": "http",
"expected_status": "200"
}'
```
See [Monitors](/docs/monitors/) for the full field reference and response shape.
## Verify
A successful list call returns `200 OK` with a JSON array. A successful create call returns `200 OK` with a `{monitor, state}` envelope. If you see `401`, check the common errors below.
## Common errors
| Symptom | Cause | Fix |
|---------|-------|-----|
| `401 Unauthorized` | Key prefix wrong or key revoked | Confirm the key starts with `mk_live_` — see [API keys](/docs/api-keys/#api-key-format) |
| `429 Too Many Requests` | Rate limit exceeded | See [Rate Limits](/docs/rate-limits/) |
| `400` on create | Invalid request body | See [Errors](/docs/errors/) — the envelope is `{"error":""}`, not RFC 7807 |
## Want this through an agent
Connect Monitive to your AI agent instead of calling the REST API directly:
- [Connect Claude Code](/docs/connect-claude-code/)
- [Connect ChatGPT](/docs/connect-chatgpt/)
- [Connect Cursor](/docs/connect-cursor/)
- [Connect via OpenAI API](/docs/connect-openai-api/)
## See also
- [MCP reference and host compatibility matrix](/docs/mcp/)
- [Monitors](/docs/monitors/) — full REST API reference
- [API keys](/docs/api-keys/) — key format and rotation
---
# API keys
> API key format, keys per environment, rotation, and common authentication errors.
To sign in to the Monitive dashboard, follow the [sign-in guide](/docs/guides/sign-in/).
## API key format
API keys use the `mk_live_` prefix followed by a random string:
```bash
Authorization: Bearer mk_live_abc123def456...
```
Keys created before 17 November 2026 start `umk_live_` and keep working.
The prefix makes keys easy to identify in logs and secret scanners.
## Multiple keys by environment
Use separate keys for different environments and tools:
- `ci-prod` — GitHub Actions and deployment pipelines.
- `local-dev` — Development and testing.
- `mcp-claude` — Claude MCP integrations.
- `mcp-cursor` — Cursor MCP integrations.
Each account supports up to 10 API keys.
## Rotation and grace window
When you rotate a key:
1. Monitive issues a new key immediately.
2. The old key remains valid for a five-minute grace window.
3. After the grace window, Monitive permanently revokes the old key.
The grace window prevents downtime during key rotation in automated systems.
## Common auth errors
The error envelope is flat: `{"error": ""}`. Match on the HTTP status first, and then match the literal validator message where needed.
| Status | Message | Meaning |
|--------|---------|---------|
| 401 | `missing authorization` | The `Authorization` header is absent. |
| 401 | `invalid credentials` | The API key isn't recognized or has been revoked. |
| 403 | `account suspended; contact support` | The account is suspended, for example, by the port-scan heuristic. Regular `/api/v1/*` calls return this error. |
| 403 | `forbidden` | A non-admin caller requested an admin-only route. The response doesn't disclose whether the route exists. |
---
# Monitors
> Create, update, delete, and query monitors via the REST API.
## Create a monitor
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"expected_status": "200"
}'
```
The target hostname must resolve at creation time — the API runs an immediate test check, and unresolvable hosts are rejected up front. For `http` monitors, that immediate check sends the configured `method`, `body`, and `headers` (see [Send a custom HTTP request](/docs/guides/custom-http-requests/)) — a non-`GET` request hits the target before the first scheduled check runs.
The response wraps the monitor and its first state snapshot:
```json
{
"monitor": {
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z"
},
"state": {
"status": "up",
"last_check_at": "2026-05-07T10:21:01Z",
"evidence_buffer": [
{
"region": "EU",
"status_code": 200,
"ttfb_ms": 182
}
]
}
}
```
> **Notes for integrators:**
> - Unknown request fields are silently ignored — the API is forward-compatible.
> - Timestamps in responses (e.g. `last_check_at`) use RFC 3339 with nanosecond precision. If your client library caps at milliseconds, truncate before parsing.
### Required fields
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Monitor name (max 255 chars) |
| `url` | string | Target URL (max 2048 chars) |
| `type` | string | `http`, `tcp`, or `ping`. The API rejects `dns` and `ssl` with `400`. |
All string fields must be valid UTF-8 with no null bytes; URL fields must additionally be free of ASCII control characters (`U+0000`–`U+001F` and `U+007F`). Violations return `400` before the SSRF guard runs.
For HTTP, TCP, and ping monitors, the immediate test check populates `state.status` with `up` or `down`. The create response uses `unknown` if the probe is unavailable, the kill switch is engaged, or the URL fails the dispatch-time SSRF guard because of DNS rebinding. A disabled monitor whose test check reports `down` also keeps `unknown` until its first scheduled check after you enable it.
### Optional fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `expected_status` | string | `"200"` | Single HTTP status code as a string (`"100"`–`"599"`). Range or list values (e.g. `"200-399"`, `"200,201"`) are rejected — see Errors. |
| `body_match` | string | — | Response body must contain this string (max 1024 chars). The field may be absent from responses when unset; treat absent and `null` identically. |
| `interval_sec` | integer | `60` | Check interval in seconds (minimum 60) |
| `enabled` | boolean | `true` | Whether the monitor is actively checking. Set `false` to pause without deleting. |
| `maintenance` | object | `{"type": "none"}` | Maintenance window. `{"type": "daily", "start_time", "end_time", "timezone"}` for a recurring window, `{"type": "once", "starts_at", "ends_at"}` for a single span, or `{"type": "none"}` to clear it. On `PUT`, omitting the field entirely leaves the stored window unchanged — it isn't the same as `{"type": "none"}`. Responses echo `starts_at`/`ends_at` normalized to UTC. See [Maintenance windows](/docs/guides/maintenance-windows/) for the full field list per type, validation errors, and the response shape. |
## Monitor types
### HTTP / HTTPS
Checks status code, optional body match, full timing breakdown (DNS, connect, TLS, TTFB, download).
### TCP
Connects to a service port. Restricted to common service ports for abuse prevention.
### Ping ICMP
Basic reachability check.
### DNS
The `dns` type is defined in the wire format but isn't available. The API rejects create and update requests for this type with `400`.
### SSL
The `ssl` type is defined in the wire format but isn't available. The API rejects create and update requests for this type with `400`.
## Check behavior
- **Monitor count** — 50 monitors per account on the free plan (see [Pricing](/pricing/))
- **Check interval** — every minute
- **Phase-spread scheduling** — checks are spread across the interval window, not clustered at the top of the minute
- **Cross-region confirmation** — any failure triggers re-checks from 2 additional regions. State flips only when 2 of 3 agree.
- **Exponential backoff** — sustained-down monitors back off from 1 min to 5 min after 10 minutes of continuous downtime
- **Flap detection** — monitors transitioning more than 10 times per hour are flagged as flapping
## List monitors
```bash
curl https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
The list endpoint returns every monitor on the account in a single response. There is no filtering or pagination — `?limit`, `?offset`, `?status`, and `?type` are accepted but silently ignored. Apply filters client-side.
The list response is a **bare JSON array** of monitor records with the current `status` and `last_check_at` flattened into each entry (no `{monitor, state}` wrapping). For the full state — including `evidence_buffer` — use `GET /api/v1/monitors/{id}`.
Response shape (abridged):
```json
[
{
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z",
"status": "up",
"last_check_at": "2026-05-07T10:21:01Z"
}
]
```
## Get a monitor
```bash
curl https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
Response (single envelope):
```json
{
"monitor": {
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z"
},
"state": {
"status": "up",
"last_check_at": "2026-05-07T10:25:43Z",
"evidence_buffer": [
{
"region": "EU",
"timestamp": "2026-05-07T10:25:43Z",
"status_code": 200,
"ttfb_ms": 174
},
{
"region": "US",
"timestamp": "2026-05-07T10:24:42Z",
"status_code": 200,
"ttfb_ms": 198
}
]
}
}
```
Every `/monitors/{monitorID}...` route accepts a ref (`-`, e.g. `k7q2mx-14`) in place of the numeric id — `curl .../monitors/k7q2mx-14` is equivalent to the numeric form above.
A value that's neither a numeric id nor a well-formed ref (e.g. `/monitors/abc`) returns `400 invalid monitor ID`. A missing id, or a ref that doesn't resolve or belongs to another account, returns `404 monitor not found` — the same body in both cases, so a caller can't distinguish "wrong account's ref" from "no such id."
## Update a monitor
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "api-prod-v2"}'
```
`PUT` accepts a partial body — fields you omit keep their current values. `PATCH` is not supported and returns `405`.
## Delete a monitor
```bash
curl -X DELETE https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
---
# Incidents
> Query the per-account incident log (30-day user-visible retention).
Down events and flap events are recorded as incidents. A monitor that goes down opens a `down` incident, which closes by setting `resolved_at` when the monitor recovers — recovery does NOT spawn a separate row. Flap events open a `flapping` incident that resolves the same way.
The API exposes a queryable log so you can build status pages, post-mortem timelines, or pipe incidents into your own alerting.
This endpoint's **user-visible promise is 30 days** — `list_incidents`/`get_incident` don't return anything older than that, by design. The underlying rows physically persist longer (95 days) so the report-email worker and status pages have enough lookback, but that longer window isn't something you can query here; for anything past 30 days, capture incidents to your own store via webhooks as they happen.
## List incidents
```bash
curl https://api.monitive.com/api/v1/incidents \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
Ordered newest first. Supports filtering and pagination via query parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| `monitor_id` | integer | Restrict to incidents for one monitor. |
| `type` | string | `down` or `flapping`. |
| `started_after` | RFC3339 datetime | Only incidents started strictly after this time. |
| `started_before` | RFC3339 datetime | Only incidents started strictly before this time. |
| `limit` | integer (1–100) | Page size. Default `50`. Out-of-range values return `400 limit must be between 1 and 100`. |
| `offset` | integer | Skip the first N results. Default `0`. |
Response shape:
```json
{
"incidents": [
{
"id": 4422,
"number": 7,
"ref": "k7q2mx-7",
"monitor_ref": "k7q2mx-14",
"monitor_id": 1287,
"account_id": 14,
"type": "down",
"started_at": "2026-05-07T09:14:02Z",
"resolved_at": "2026-05-07T09:18:51Z",
"evidence": [
{
"region": "EU",
"timestamp": "2026-05-07T09:14:01Z",
"status_code": 503,
"ttfb_ms": 2143
},
{
"region": "US",
"timestamp": "2026-05-07T09:14:00Z",
"status_code": 503,
"ttfb_ms": 2087
}
],
"created_at": "2026-05-07T09:14:02Z",
"maintenance": false
}
],
"total": 1,
"limit": 50,
"offset": 0
}
```
`resolved_at` is **absent** (the key is omitted from the JSON object) while the incident is still ongoing; it appears once the monitor recovers. `maintenance` is always present as `true` or `false` — never omitted — and is set once, when the incident opens: `true` if the monitor's maintenance window was active at that instant, `false` otherwise (including for every incident on a monitor with no maintenance window configured). See [Maintenance windows](/docs/guides/maintenance-windows/) for how this flag interacts with alert delivery. `total` reports the count of incidents matching the supplied filters (`monitor_id`, `type`, `started_after`, `started_before`) — paginate against this number, not the entire 30-day window.
## Get an incident
```bash
curl https://api.monitive.com/api/v1/incidents/4422 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
The response wraps the incident under an `incident` key:
```json
{
"incident": {
"id": 4422,
"number": 7,
"ref": "k7q2mx-7",
"monitor_ref": "k7q2mx-14",
"monitor_id": 1287,
"account_id": 14,
"type": "down",
"started_at": "2026-05-07T09:14:02Z",
"resolved_at": "2026-05-07T09:18:51Z",
"evidence": [],
"created_at": "2026-05-07T09:14:02Z",
"maintenance": false
}
}
```
`{incidentID}` takes either a numeric id or a ref (`-`, e.g. `k7q2mx-7`):
```bash
# equivalent to the numeric form above
curl https://api.monitive.com/api/v1/incidents/k7q2mx-7 \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
A value that's neither a numeric id nor a well-formed ref returns `400 invalid incident ID`. A missing id, or a ref that doesn't resolve or belongs to another account, returns `404 incident not found` — the same body in both cases, so a caller can't distinguish "wrong account's ref" from "no such id."
## Incident types
| `type` | Meaning |
|--------|---------|
| `down` | Monitor transitioned from up to down. Resolves when it transitions back to up. |
| `flapping` | Monitor crossed the flap threshold (more than 10 transitions per hour). Resolves when traffic stabilises. |
The `up` type is reserved for future use and is not currently emitted.
---
# Webhooks
> Account-level webhook recipients, the deprecated monitor-scoped webhook endpoint, payload format, signature verification, retry policy, and the account-wide delivery log.
**Need an alert that actually wakes you up?** Browser push and email both get silently dropped by Do Not Disturb. See the [Reliable alerts guide](https://monitive.com/guides/reliable-alerts) — wire your webhook to Pushover (bypasses Do Not Disturb on iOS and Android) or ntfy on Cloudflare Workers.
## Create an account-level webhook recipient
A webhook recipient is an account-level destination: create it once, then attach it to any number of monitors — see [Choose who gets alerts](/docs/guides/alert-recipients/) for the attach/detach semantics. Use `POST /api/v1/recipients` with `type: "webhook"`:
```bash
curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"ops-webhook","type":"webhook","config":{"url":"https://hooks.example.com/incident"}}'
```
Response:
```json
{
"id": 42,
"name": "ops-webhook",
"type": "webhook",
"config": {"url": "https://hooks.example.com/incident"},
"default": false,
"status": "active",
"events": ["down", "up", "flapping"],
"monitor_ids": [],
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z",
"secret": "whs_live_…"
}
```
**The plaintext HMAC `secret` is returned only in this creation response.** `GET /api/v1/recipients/{id}` (and every other read of this recipient) omits it — copy the secret now, since Monitive won't show it again.
Attach the recipient to a monitor with `PUT /api/v1/monitors/{monitorID}/recipients` (full-replacement semantics) or at creation time via `create_monitor`'s `recipient_ids`/`recipients` arguments — see [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp).
**Rotating a webhook recipient's secret.** There's no rotate endpoint — a webhook recipient's secret is set once, at creation, and never changes. To rotate it, create a replacement recipient and move every attached monitor to it. Done carelessly, this leaves every monitor that was on the old recipient unalerted for however long it takes to reattach them by hand — and deleting the old recipient too soon can silently discard a real queued alert, since `DELETE /api/v1/recipients/{recipientID}` deletes that recipient's own pending/retrying deliveries along with the attachment (see [Detaching a recipient vs. deleting it](/docs/guides/alert-recipients/#detaching-a-recipient-vs-deleting-it)). **The delivery log can only tell you what was queued as of your last read — it can't prove nothing is queued at the instant you delete.** A paginated scan that finds no `pending`/`retrying` rows reflects that moment only; a state transition that fires between your last scan and the `DELETE` call still queues a delivery that deletion discards outright, and there's no API to freeze new deliveries while you check. Neither procedure below is atomic end-to-end, but both keep every monitor attached to a live recipient throughout. Treat an empty scan as a floor, not a proof — keep the old recipient around for at least the longest retry delay (2 hours; see [Retry policy](#retry-policy)) after its last queued delivery appeared resolved before deleting it, for margin against a delivery that queues in that gap. Pick a procedure based on what your receiver can verify at once — there is no single procedure that closes both gaps for every receiver.
### Dual-secret overlap
Use this when your receiver can verify two secrets at once.
1. **Prepare your receiver before creating anything.** You're about to have two valid secrets during the overlap — the one already in use, and the new one. Update your receiver to check an incoming signature against both candidates, each with its own `crypto.timingSafeEqual` (or language equivalent) comparison, for the whole rotation.
2. **Read and save the recipient being rotated.** `GET /api/v1/recipients/{recipientID}` for its `name`, `default`, and `events`, plus its `monitor_ids`.
3. **Create the replacement** with the same `name`, `default`, and `events`. Copy its new `secret` from the creation response and install it at the receiver *alongside* the still-valid original secret — both must verify successfully right now.
4. **Attach the replacement to every saved monitor with `grace_s` set to `120`**, using the read-merge-write `recipients` form described in [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp) — read each monitor's current `recipients` array first and submit the complete set, so no other recipient already on that monitor gets dropped. Note the wall-clock time this attach completes; step 7 needs it.
5. **Verify delivery reaches the replacement** using `POST /api/v1/recipients/{recipientID}/test` against the replacement, or by triggering a controlled down/up transition on one affected monitor. Don't wait for the next scheduled check as "verification" — a healthy monitor's next check doesn't by itself produce a delivery; webhooks fire only on a qualifying state transition or an explicit test send.
6. **Re-verify attachments before waiting out deliveries.** Re-read every affected monitor's own `recipients` array directly (not just the rotated recipient's `monitor_ids`) and confirm the replacement is attached on each one — retry the attach step for any monitor where it's missing. Separately, re-read the rotated recipient's current `monitor_ids`, in case a monitor was created mid-rotation and auto-attached a `default` recipient that was never in your step 2 snapshot — attach the replacement there too, and add its id to the set of monitors you check in step 7: that set is the union of the step 2 snapshot and every id discovered here, never just the snapshot alone.
7. **Wait out the old recipient's queued deliveries, then delete it.** For every monitor in that union set — the step 2 snapshot plus every id discovered in step 6 — call `GET /api/v1/webhook-deliveries?monitor_id={monitorID}&status=pending&limit=100`, then the same with `status=retrying`. `webhook-deliveries` has no recipient-id filter, so read `total` from each response and keep increasing `offset` by the page size, re-querying until you've walked every page for that monitor and status — a single-page read can leave an older row for the old recipient unseen behind newer rows for other recipients on the same monitor. Across every page, look for rows whose `webhook_id` equals the old recipient's id and whose `created_at` is before the attach time that applies to that monitor (step 4's time for the original snapshot, step 6's for anything discovered there). If any show up, wait and re-query — the retry schedule's longest gap is 2 hours, so a row can take that long to resolve — repeating the full paginated scan each time, until a complete scan of every page finds none of them still `pending`/`retrying` (each has moved to `delivered`, `failed`, `superseded`, or `cancelled`). Immediately before deleting, re-read the rotated recipient's `monitor_ids` once more; if anything new appeared since step 6, attach the replacement there too and wait out its deliveries with the same full paginated scan before continuing. **This scan proves nothing was queued as of the last page read — it cannot prove nothing is queued at the instant the next step's `DELETE` runs.** Anything still queued at that instant is lost outright, not delivered late; for margin against that gap, don't delete immediately on a clean scan — wait at least the 2-hour retry window past it first.
8. **Only now delete the rotated recipient** (`DELETE /api/v1/recipients/{recipientID}`), and retire its secret at the receiver.
Between step 4 and step 8, both the rotated recipient and its replacement are attached, so any alert that fires in that window delivers twice; that's the deliberate trade against a gap where nothing is attached.
### Downtime window
Use this when your receiver can only hold one secret at a time — there is no gap-free path through the dual-secret overlap above, so take a short, explicit downtime window instead. Even here, never replace the old recipient on a monitor before the replacement already covers it: the old recipient stays attached, with its queued deliveries given time to resolve, until after the swap — the window in this path is at the receiver's secret, not at the recipient attachment.
1. **Read and save the recipient being rotated** — the same information as dual-secret step 2.
2. **Create the replacement** with the same `name`, `default`, and `events`. Hold its new `secret` from the creation response; don't install it at the receiver yet — the old secret needs to keep working through step 4.
3. **Attach the replacement alongside the old recipient on every saved monitor, one `PUT` per monitor**, using the read-merge-write `recipients` form: submit the full current set with the replacement added (with `grace_s` set to `120`) and the old recipient still present — this step never removes the old recipient. Note the wall-clock time the last of these `PUT`s completes; step 4 needs it.
4. **Re-verify attachments, then wait out the old recipient's queued deliveries while its secret is still installed and the receiver is still running it** — the same checks as dual-secret steps 6 and 7 (including their union-set coverage of any monitor discovered mid-rotation), substituting the attach time noted in step 3 for the attach time. Don't proceed until every old-only queued delivery has resolved (`delivered`, `failed`, `superseded`, or `cancelled`) — and remember that scan is a snapshot, not a guarantee: it can't see a delivery that queues after the last page was read.
5. **Take the receiver offline** (stop the process, or block its route), swap its secret — remove the old one, install the new one — and bring it back online. Do this immediately after step 4's scan comes back clean, to minimize the gap in which a new delivery could queue for the old recipient and be lost; step 4 cannot guarantee that gap is empty, only that it's short.
6. **Verify delivery reaches the replacement** using `POST /api/v1/recipients/{recipientID}/test`, or a controlled down/up transition — same caveat as dual-secret step 5.
7. **Only now detach the old recipient from every saved monitor** (read-merge-write `PUT`, removing just the old id) **and delete it** (`DELETE /api/v1/recipients/{recipientID}`), and retire its secret at the receiver.
Between step 3 and step 5, both recipients are attached: the old recipient keeps delivering normally since its secret is still installed, while a delivery to the replacement fails signature verification at the receiver until step 5 switches the secret — that failure retries on the normal backoff and resolves once the secret is switched. That's the explicit cost of this path instead of the dual-secret overlap's double delivery. Unlike a swap that replaces old for new in one step, the old recipient here is never detached before the replacement already covers every monitor, so a crash at any point before step 7 still leaves every monitor attached to at least one recipient whose deliveries actually go through.
Both procedures assume no other writer changes any affected monitor's recipient attachments for the entire duration, not only during monitor creation — nothing in the API enforces that assumption, so each procedure's re-verify step is a mitigation against a concurrent change, not a guarantee against one. No step in either procedure is atomic with any other: a crash partway through can leave some monitors on the old recipient and some on the new one, so re-check every affected monitor's attached recipients afterward if a step fails.
## Legacy monitor-scoped webhook endpoint (deprecated)
Before account-level recipients existed, each monitor had exactly one webhook slot set directly on the monitor. `PUT/GET/DELETE /api/v1/monitors/{monitorID}/webhook` still work today as a deprecated alias implemented on top of the recipient model above, but two things differ from an account-level webhook recipient:
- **One webhook per monitor, not reusable across monitors.** This alias can't attach the same webhook destination to a second monitor — use the account-level recipient endpoint above for that.
- **The secret is readable on every `GET`, not shown once.** Unlike the account-level recipient's create-only secret, `GET /api/v1/monitors/{monitorID}/webhook` returns the plaintext secret every time it's called — treat this endpoint as a standing credential surface (anyone who can authenticate to the account with at least member access can recover the signing key by calling `GET`).
```bash
curl -X PUT https://api.monitive.com/api/v1/monitors/1287/webhook \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/incident"}'
```
Response:
```json
{
"id": 42,
"monitor_id": 1287,
"url": "https://hooks.example.com/incident",
"secret": "whs_live_…",
"created_at": "2026-05-19T12:00:00Z"
}
```
Replacing the URL on an existing webhook keeps the existing secret. To rotate the secret, `DELETE` the webhook then `PUT` it again — but this alias has exactly one slot per monitor and no read-merge-write equivalent to the account-level recipient's rotation procedure above: deleting it leaves the monitor with **no webhook at all** until the new `PUT` succeeds. A `GET` beforehand can capture the existing `url` *and* `secret` — unlike the account-level recipient's create-only secret, this alias's `GET` returns the plaintext secret every time (see below). But that saved secret doesn't help you recover: recreating the webhook with `PUT` always issues a brand-new `secret`, never the one you saved, so the receiver still needs its signing secret updated either way, and if the new `PUT` fails partway through there is no atomic rollback to the monitor's previous working webhook. For a new setup, use the account-level recipient above instead — it's reusable across monitors and its rotation procedure keeps a live, verified recipient attached throughout instead of leaving the monitor with no webhook at all mid-rotation.
```bash
# Read the current webhook for a monitor (returns the plaintext secret too, every time)
curl https://api.monitive.com/api/v1/monitors/1287/webhook \
-H "Authorization: Bearer $MONITIVE_API_KEY"
# Remove the webhook (monitor stays; just no notifications)
curl -X DELETE https://api.monitive.com/api/v1/monitors/1287/webhook \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
## Payload format
```json
{
"event": "monitor.down",
"monitor_ref": "k7q2mx-14",
"monitor_name": "myapp-healthz",
"monitor_url": "https://example.com/health",
"account_handle": "k7q2mx",
"occurred_at": "2026-04-12T14:23:11Z",
"reason": "http_5xx",
"delivery_id": 3,
"attempt": 1
}
```
Events: `monitor.down`, `monitor.up`, `monitor.flapping`.
| Field | Type | Description |
|-------|------|-------------|
| `event` | string | One of `monitor.down`, `monitor.up`, `monitor.flapping`. |
| `monitor_ref` | string | Ref of the monitor that changed state — accepted anywhere `/monitors/{monitorID}` takes an id. |
| `monitor_name` | string | Display name of the monitor. |
| `monitor_url` | string \| omitted | The URL being monitored. Omitted if the monitor has no URL. |
| `account_handle` | string | The six-character handle of the account that owns the monitor. |
| `occurred_at` | RFC3339 string | When the state transition was detected. |
| `reason` | string \| omitted | Error class for `monitor.down` (e.g. `http_5xx`, `timeout`), flap reason for `monitor.flapping`, empty/omitted for `monitor.up`. |
| `delivery_id` | integer | Stable per logical state transition. Use this field to deduplicate retried deliveries — the same transition always carries the same `delivery_id`. |
| `attempt` | integer (1–5) | Which delivery attempt this is (1 = first try). |
**Payloads no longer carry a numeric `monitor_id` or `account_id`.** A receiver that keyed on either field must switch to `monitor_ref` and `account_handle`. During the rollout, accept both identifier pairs: a retry keeps its `delivery_id` but rebuilds its body from the current payload shape each time it's sent, so a delivery whose retries straddle the deploy can arrive once with `monitor_id`/`account_id` and once with `monitor_ref`/`account_handle`.
## Signature verification
Every webhook delivery includes an `X-UptimeMonitoring-Signature` header containing an HMAC-SHA256 hex digest. To verify it, compute the HMAC over the **raw request bytes** (not a re-serialized parse), then compare with a **constant-time** function. Using a regular string comparison (`===` / `!==`) leaks timing information that lets an attacker recover the expected signature byte-by-byte.
:::caution
Always verify against the raw body bytes, not a re-serialized parse of the body. Always use a constant-time comparison — `===` or `!==` is not safe here.
:::
**During a [secret rotation](#create-an-account-level-webhook-recipient), your receiver must accept either of two candidate secrets at once** — the one already in use and the new one — each checked with its own constant-time comparison, for the whole overlap. The examples below check a list of one or two candidate secrets rather than a single fixed value, so they work unchanged during a rotation. A receiver that can only hold one secret can't take the gap-free rotation path; it needs a documented downtime window instead.
```js
const crypto = require('crypto');
const express = require('express');
const app = express();
// Parsed once at startup, never per-request. A blank or trailing-comma
// entry would otherwise add an empty-string HMAC key, and an attacker who
// knows that can compute a valid signature against it — so a config typo
// must abort startup instead of silently accepting forged requests.
function loadCandidateSecrets() {
const raw = process.env.MONITIVE_WEBHOOK_SECRETS || '';
const candidates = raw.split(',').map((s) => s.trim());
if (candidates.length > 2 || candidates.some((s) => s.length === 0)) {
throw new Error(
'MONITIVE_WEBHOOK_SECRETS must be one or two nonempty, comma-separated secrets (no empty entries, no trailing comma)',
);
}
return candidates;
}
const CANDIDATE_SECRETS = loadCandidateSecrets();
// Register this route BEFORE any global express.json() or body-parser middleware.
// Earlier middleware consumes the stream first; express.raw() must run here, not after.
app.post(
'/webhooks/monitive',
express.raw({ type: 'application/json' }),
(req, res) => {
if (!Buffer.isBuffer(req.body)) {
return res.status(400).send('Expected raw body — check middleware order');
}
const sig = req.header('X-UptimeMonitoring-Signature') || '';
if (!/^[a-f0-9]{64}$/i.test(sig)) {
return res.status(401).send('Invalid signature');
}
const a = Buffer.from(sig, 'hex');
const matches = CANDIDATE_SECRETS.some((secret) => {
const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const b = Buffer.from(expected, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
});
if (!matches) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
// …handle event.event === 'monitor.down' / 'monitor.up' / 'monitor.flapping'…
res.status(204).end();
},
);
app.listen(3000);
```
```python
import hmac
import hashlib
import os
from flask import Flask, request, abort
app = Flask(__name__)
def load_candidate_secrets():
# Parsed once at startup, never per-request. A blank or trailing-comma
# entry would otherwise add an empty-string HMAC key, and an attacker
# who knows that can compute a valid signature against it — so a
# config typo must abort startup instead of silently accepting forged
# requests.
raw = os.environ.get("MONITIVE_WEBHOOK_SECRETS", "")
candidates = [s.strip() for s in raw.split(",")]
if len(candidates) > 2 or any(not s for s in candidates):
raise RuntimeError(
"MONITIVE_WEBHOOK_SECRETS must be one or two nonempty, "
"comma-separated secrets (no empty entries, no trailing comma)"
)
return [s.encode() for s in candidates]
# One candidate secret in steady state; two during a rotation overlap.
CANDIDATE_SECRETS = load_candidate_secrets()
@app.post("/webhooks/monitive")
def receive():
raw = request.get_data() # bytes, before any parsing
sig = request.headers.get("X-UptimeMonitoring-Signature", "")
matches = any(
hmac.compare_digest(sig, hmac.new(secret, raw, hashlib.sha256).hexdigest())
for secret in CANDIDATE_SECRETS
)
if not matches:
abort(401)
# event = json.loads(raw)
return "", 204
if __name__ == "__main__":
app.run(port=3000)
```
Background: [OWASP — Observable Timing Discrepancy (CWE-208)](https://cwe.mitre.org/data/definitions/208.html).
## Retry policy
This table describes **webhook recipients only**. A Slack recipient retries only a transport error, `429`, or `5xx` — any other non-2xx response fails the delivery on the first attempt, with no retry; see the [Slack alerts guide](/docs/guides/slack-alerts/) for that recipient type's behavior.
Failed webhook deliveries (non-2xx response or timeout) are retried with exponential backoff:
| Attempt | Delay |
|---------|-------|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
After 5 failed attempts, the delivery is marked as failed.
## Delivery log account-wide
The delivery log is exposed at the account scope, not per-webhook. Filter with `monitor_id` if you only want one monitor's deliveries:
```bash
curl "https://api.monitive.com/api/v1/webhook-deliveries?monitor_id=1287&limit=20" \
-H "Authorization: Bearer $MONITIVE_API_KEY"
```
| Query | Type | Description |
|-------|------|-------------|
| `monitor_id` | integer | Restrict to deliveries for one monitor. |
| `since` | RFC3339 datetime | Only deliveries dispatched at or after this time. |
| `status` | string | Filter by delivery status: `pending`, `retrying`, `delivered`, `failed`, `superseded`, or `cancelled`. |
| `limit` | integer (1–100) | Page size. Default `50`. |
| `offset` | integer | Skip the first N results. |
Response shape:
```json
{
"deliveries": [
{
"id": 9001,
"webhook_id": 42,
"monitor_id": 1287,
"account_id": 14,
"event_type": "monitor.down",
"status": "delivered",
"attempt_count": 1,
"last_response_code": 200,
"last_attempt_at": "2026-05-07T09:14:05Z",
"next_attempt_at": "2026-05-07T09:14:05Z",
"created_at": "2026-05-07T09:14:02Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
```
Each delivery record includes: `id`, `webhook_id` (a recipient id — the field name is kept for wire compatibility, but it identifies a webhook, email, Slack, or PagerDuty recipient, whichever type the delivery was for), `monitor_id`, `event_type`, `status` (`pending|retrying|delivered|failed|superseded|cancelled`), `attempt_count`, `last_response_code`, `last_attempt_at`, `next_attempt_at`, `cancelled_at` (set only when `status` is `cancelled`), and `created_at`. A `superseded` row means an older queued delivery for the same recipient+monitor pair was replaced by a newer one; a `cancelled` row means a `down` delivery's outage recovered inside the two-minute grace, or its recipient's `events` filter narrowed to drop `down` while the row was still queued — either way, `pending`/`retrying` is where delivery guarantees apply, not these two. There is no per-webhook delivery endpoint — `GET /api/v1/webhooks/{id}/deliveries` does not exist.
---
# Browser push notifications
> Why push exists, how to enable it, events, and browser limitations.
## Why push exists
Browser push notifications are the lowest-friction alert channel — one-click opt-in, no address to manage, and instant delivery. Use them alongside or instead of [webhooks](/docs/webhooks/) and [email alerts](/docs/guides/email-alerts/).
## How to enable
1. Log in to [my.monitive.com](https://my.monitive.com)
2. Click the bell icon or "Enable notifications" prompt
3. Allow notifications in your browser
That's it. No email, no phone number, no configuration.
## What events trigger notifications
- **Monitor down** — when a monitor's state flips to down (after cross-region confirmation)
- **Monitor up** — when a previously-down monitor recovers
## Subscription management
Manage your push subscriptions from the dashboard. You can:
- View active subscriptions (browser + OS)
- Remove individual subscriptions
- Test notifications
## Known browser limitations
- **Safari on iOS** — requires adding the site to your home screen first
- **Incognito / private mode** — push subscriptions don't persist
- **Multiple devices** — each browser/device requires a separate opt-in
- **Browser must be running** — notifications queue until the browser is open (behavior varies by OS)
---
# Alert bridge: self-hosted Cloudflare Worker
> Deploy the open-source alerts-bridge to your own Cloudflare Worker to receive Monitive webhook events as Pushover, ntfy, Slack, Discord, or Telegram notifications.
## What it is
The alerts-bridge is an open-source Cloudflare Worker that translates Monitive webhook events into push notifications. Deploy it once to your own Cloudflare account and every `monitor.down`, `monitor.up`, and `monitor.flapping` event reaches your phone, Slack workspace, or Discord server — via Pushover, ntfy, Slack, Discord, or Telegram.
You own the Worker. Monitive sends the webhook; the bridge forwards it to your provider. No third-party relay, no vendor lock-in.
New to this? The [Reliable alerts guide](/guides/reliable-alerts) covers why Do Not Disturb makes browser push and email unreliable, and lets you pick a provider and runtime. This page is the full deploy reference.
## Prerequisites
- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (free tier is enough)
- Node 20 or newer
- A Monitive account with at least one monitor
- A provider account — this walkthrough uses [Pushover](https://pushover.net/)
## Get the code
```bash
git clone https://github.com/uptimemonitoring/alerts-bridge
cd alerts-bridge
npm install
```
## Deploy
Log in to Cloudflare, then deploy:
```bash
npx wrangler login
npm run deploy
```
Wrangler prints the Worker URL when the deploy succeeds:
```
Published alerts-bridge (0.00 sec)
https://alerts-bridge..workers.dev
```
Note that URL — you register it with your monitor next.
## Wire to Monitive
1. Go to **Recipients** in [my.monitive.com](https://my.monitive.com) and click **Create recipient**.
2. Choose **Webhook**, paste the `*.workers.dev` URL from the deploy step, and click **Create recipient**.
3. Copy **Your recipient secret** — shown once — you'll paste it as `MONITOR_WEBHOOK_SECRETS` in the next step.
4. Open your monitor's **Recipients** section, check the new recipient, and save.
(API equivalent: `POST /api/v1/recipients` with `type: "webhook"` returns the `secret` once in the creation response; attach the recipient to a monitor with `PUT /api/v1/monitors//recipients` — see [Choose who gets alerts](/docs/guides/alert-recipients/).) The bridge verifies the `X-UptimeMonitoring-Signature` header against this secret on every request — see [Webhooks](/docs/webhooks) for the signature contract.
## Set secrets
Configure the Worker secrets with `npx wrangler secret put`. Wrangler prompts you for each value; nothing is written to disk.
```bash
# Which provider to use
npx wrangler secret put PROVIDER
# → pushover
# Pushover application token (from pushover.net → Your Applications)
# Tip: name the Pushover application "Monitive" — that name is what
# shows as the source on each push notification.
npx wrangler secret put PUSHOVER_TOKEN
# Pushover user key (from pushover.net → Your User Key)
npx wrangler secret put PUSHOVER_USER
# The whs_live_… signing secret you copied from the recipient's creation response above
npx wrangler secret put MONITOR_WEBHOOK_SECRETS
```
:::caution
Never commit these values to source control. `wrangler secret put` stores them as encrypted Cloudflare secrets, not in `wrangler.toml`. Secrets apply to the live Worker immediately — no redeploy needed.
:::
## Test
Watch the Worker logs in one terminal:
```bash
npx wrangler tail
```
Then trigger a real event: point the monitor at a URL that returns 5xx (or stop the service it watches) so Monitive fires a `monitor.down` webhook, then restore it to fire `monitor.up`. Confirm each notification arrives on your device, and watch `wrangler tail` for the incoming request and the provider's response.
The webhook recipient's **Send test** button (on its row in **Recipients**) is the fastest way to fire a sample delivery without affecting the monitor's real state.
## Provider reference
Set `PROVIDER` to one of the values in the first column and supply the corresponding secrets:
| `PROVIDER` value | Required secrets | Notes |
|---|---|---|
| `pushover` | `PUSHOVER_TOKEN`, `PUSHOVER_USER` | Pushover app token + user key |
| `ntfy` | `NTFY_TOPIC` (+ optional `NTFY_URL`, `NTFY_TOKEN`) | `NTFY_URL` defaults to `https://ntfy.sh`; `NTFY_TOKEN` only for protected topics |
| `slack` | `SLACK_WEBHOOK_URL` | Slack incoming webhook URL |
| `discord` | `DISCORD_WEBHOOK_URL` | Discord webhook URL |
| `telegram` | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | Bot token + target chat ID |
## Troubleshooting
**401 from the Worker**
The signature verification failed. Check that the `MONITOR_WEBHOOK_SECRETS` value in the Worker matches the recipient secret you copied at creation time exactly — trailing whitespace or a copy-paste error will cause every request to be rejected. Monitive doesn't show that secret again, and there's no rotate endpoint — don't just delete the recipient and create a new one: that leaves every monitor attached to it unalerted until you reattach them by hand, and deleting a recipient also discards whatever of its deliveries are still queued (`pending`/`retrying`) at that moment, outright. Instead, follow one of the two procedures on the [Webhooks](/docs/webhooks/#create-an-account-level-webhook-recipient) page, picking based on what the Worker can verify at once:
- **Dual-secret overlap**, if your deployed version of the bridge checks multiple candidate secrets: create the replacement, install its secret in the Worker alongside the still-valid original, attach it to every monitor the original was on, verify delivery with **Send test** or a controlled down/up transition, then wait out the original's queued deliveries and delete it.
- **Downtime window**, if the Worker can only hold one secret: create the replacement, take the Worker offline, swap old for new on every affected monitor (one `PUT` per monitor), install the new secret and bring the Worker back online, verify delivery, then wait out and delete the original the same way.
Either path, a clean delivery-log scan only proves nothing was queued as of that read — it can't prove nothing is queued the instant you call `DELETE`, since a transition firing in that gap still queues a delivery that deletion discards outright, not delivers late. The Webhooks page's procedures show how to run that scan; for margin against that gap, keep the original recipient around for at least the longest retry delay (2 hours) past a clean scan before deleting it.
**No push notification**
Signature passed but the provider rejected the request. Double-check `PUSHOVER_TOKEN` and `PUSHOVER_USER` (or the equivalent for your provider). Run `npx wrangler tail` while triggering a test event to see the provider's error response.
**413 Request Entity Too Large**
The webhook payload exceeded the Worker's request size limit. This should not happen with standard Monitive payloads — if it does, open an issue in the alerts-bridge repository.
---
# Feeds
> Per-account incident feed (Atom XML over the RSS-shaped URL) and shareable incident URLs.
## Per-account incident feed
Every account exposes an Atom XML feed of incidents at a single URL:
```
https://api.monitive.com/feed/{token}/rss
```
The path segment is `feed` (singular, not `/api/v1/feeds/...`). The body is Atom XML even though the path ends in `/rss` — the suffix is preserved for client compatibility, but there is no separate `/atom` route.
The token IS the credential — it carries no `Bearer` header, and anyone with the URL can read the feed. Treat it like a password. Find or rotate it from the dashboard under **Feeds**.
Subscribe from Slack, RSS readers, or automation tools. Most readers handle Atom transparently.
For a single monitor's own public RSS/Atom feed, see the [Status page](/docs/guides/free-status-page/) guide.
> **Treat the URL like an API key.** The token appears in HTTP referer headers, web-server logs, and any system that processes the URL. Rotate it from the dashboard if it's exposed (paste into the wrong chat, leaked in a screenshot, etc.).
## Shareable incident feed URL
You can generate a read-only permalink for your incident feed. This is useful for:
- Sharing with team members who don't have an account
- Embedding in internal status dashboards
- Providing a human-readable fallback alongside webhooks
Manage shareable feed URLs from the dashboard.
## Platform news feed
A separate feed for platform announcements (maintenance, new features, policy changes) is available at:
```
https://api.monitive.com/feed.xml
```
The body is Atom XML and is open (no auth). Subscribe from your feed reader of choice.
---
# GitHub Action: assert healthy after deploy
> Fail a deploy if health never comes back.
*Available since v1.0.0 (May 2026).*
## What it does
The `uptimemonitoring/assert-healthy` action polls a monitor and fails the workflow step if the monitor doesn't report healthy within a timeout window. Built for post-deploy health gates.
## Minimal workflow
```yaml
- name: Verify deploy health
uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-id: ${{ vars.MONITOR_ID }}
timeout: 120
```
## Inputs
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `api-key` | Yes | — | Monitive API key |
| `monitor-id` | Yes | — | Monitor ID to check |
| `timeout` | No | `120` | Max seconds to wait for healthy |
| `base-url` | No | `https://api.monitive.com` | API base URL |
## Outputs
| Output | Description |
|--------|-------------|
| `healthy` | `true` or `false` |
| `last-status` | Last observed monitor status |
| `last-region` | Region of last check |
| `last-ttfb-ms` | TTFB of last check |
## Advanced usage
### Custom timeout
```yaml
- name: Verify deploy health
uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-id: ${{ vars.MONITOR_ID }}
timeout: 180
```
:::note[Custom API base URL]
The `base-url` input lets the action target a compatible API endpoint. Omit it to use the canonical Monitive API:
```yaml
- name: Verify deploy health
uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-id: ${{ vars.MONITOR_ID }}
base-url: https://api.example.com
timeout: 180
```
:::
### Using in a matrix
The block below is a `jobs..steps:` fragment — drop it into a full workflow with `name`, `on`, and `runs-on` already declared:
```yaml
jobs:
assert-healthy:
runs-on: ubuntu-latest
strategy:
matrix:
monitor: [1287, 1288, 1289]
steps:
- uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-id: ${{ matrix.monitor }}
```
---
# Errors
> Error envelope, observed messages, and common error responses.
## Error envelope
The `/api/v1/*` surface uses a flat envelope:
```json
{
"error": "url is required"
}
```
The `error` field is always a single human-readable string for these endpoints. There is no `code`, `message`, or nested object — clients should match on the HTTP status and (where useful) the literal `error` string.
There are two documented exceptions:
- The `/oauth2/*` endpoints (`/oauth2/register`, `/oauth2/token`, `/oauth2/revoke`) follow RFC 7591 / RFC 6749 and return `{"error":"", "error_description":""}` (e.g. `{"error":"invalid_client_metadata","error_description":"redirect_uris is required"}`).
- The monitor-test endpoint's kill-switch 503 carries `{error, message}` — see [503 Kill-switch](#503-kill-switch-active-test-monitor-endpoint-only) below.
## Common messages
A representative — not exhaustive — list of the literal `error` strings the API returns today, grouped by HTTP status. New endpoints add new strings; pin clients on the HTTP status first and only fall back to literal-string matching where the wording is part of an established contract (validator output, rate-limit hints).
### 400 Bad Request
| Message | When |
|---------|------|
| `name is required` | Create monitor body missing `name` |
| `url is required` | Create monitor body missing `url` |
| `interval_sec must be at least 60` | `interval_sec` below the 60-second minimum |
| `expected_status must be a single integer between 100 and 599` | `expected_status` non-integer or out of range |
| `type must be one of: down, flapping` | Invalid incident `type` query value |
| `limit must be between 1 and 100` | Pagination `limit` out of range |
| `invalid monitor ID` | Path parameter on monitor endpoints is neither a numeric id nor a well-formed ref (e.g. `/monitors/abc`) |
| `invalid incident ID` | Path parameter on `/api/v1/incidents/{id}` is neither a numeric id nor a well-formed ref |
| `invalid key ID` | Path parameter is non-numeric on key endpoints |
| `invalid request body` | Body is not valid JSON |
| `label must be at least 3 characters` | Key label below the minimum length |
| `label must be 100 characters or less` | Key label above the maximum length |
| `missing code` | OAuth callback missing `code` query parameter |
| `invalid or expired code` | OAuth callback `code` rejected by GitHub |
| `url rejected: ip is in a blocked range` | Target URL resolves to a blocked IP range (SSRF guard) |
### 401 Unauthorized
| Message | When |
|---------|------|
| `missing authorization` | No `Authorization` header |
| `invalid credentials` | API key not recognised or revoked |
### 403 Forbidden
| Message | When |
|---------|------|
| `account suspended; contact support` | Account suspended (e.g. by the port-scan heuristic). Returned on `/api/v1/*`. |
| `forbidden` | Admin-only route hit by a non-admin caller. Opaque on purpose. |
### 404 Not Found
| Message | When |
|---------|------|
| `monitor not found` | Monitor id or ref is a numeric id or well-formed ref that does not resolve for this account |
| `incident not found` | Incident id or ref is a numeric id or well-formed ref that does not resolve for this account |
| `key not found` | API key ID does not exist on this account |
### 409 Conflict
| Message | When |
|---------|------|
| `cannot delete last key` | Tried to delete the only remaining API key |
| `key limit reached` | Account already at the 10-key cap |
### 429 Too Many Requests
Rate-limit responses carry a route-specific message in the flat envelope plus a `Retry-After` header (seconds). Examples:
| Limiter | Message |
|---------|---------|
| Account-wide `/api/v1/*` cap | `account rate limit exceeded; retry in s` |
| Monitor-creation cap | `monitor creation rate limit exceeded; retry in s` |
| Per-monitor manual-test minimum interval | `too many tests for this monitor; retry in s` |
| Per-domain cross-account test cap | `domain rate limit exceeded; retry in s` |
Don't pin clients on a single literal string; honour `Retry-After` and treat any 429 as transient.
### 500 Internal Server Error
The body is `{"error":"internal error"}`. Retry with exponential backoff.
### 503 Kill-switch active test-monitor endpoint only
`POST /api/v1/monitors/{id}/test` is the one endpoint where the 503 body deviates from the flat envelope. When the dispatcher's global kill switch is engaged, the test endpoint returns:
```json
{
"error": "kill_switch_active",
"message": "check dispatches temporarily disabled"
}
```
with a `Retry-After` header. Both `error` and `message` are present. Other 503s (e.g. `kill switch not configured` on admin endpoints) keep the flat `{"error":"..."}` shape.
## Common scenarios
### SSRF blocked
```json
{
"error": "url rejected: ip 10.0.0.5 is in a blocked range"
}
```
Private IPs (10.x, 172.16-31.x, 192.168.x), loopback, and link-local addresses are blocked. See [Security](/docs/security/) for details.
### Validation failure
```json
{
"error": "expected_status must be a single integer between 100 and 599"
}
```
The body is the literal validator output — useful to surface back to the user.
---
# Rate limits
> Every limit the Monitive API enforces, the response you get when you hit one, and which headers to read.
The API allows 200 requests per minute per account, and some endpoints add tighter limits on top. Going over a rate limit usually returns `429 Too Many Requests` with a `Retry-After` header: wait that many seconds, then retry. Some limits instead return another status, suppress a background delivery, replace an existing resource, or return an MCP tool error. Each section documents its exception; see [Handling 429 responses](#handling-429-responses). Rate limits never suspend your account.
## API requests per account
Your account can make 200 requests per minute. The limit is a token bucket: a full allowance lets you send up to 200 requests at once, and it refills continuously at 200 per minute.
Every API key, dashboard session, and OAuth token on the account shares one allowance. The limit is not per key.
Most requests to registered authenticated `/api/v1` routes spend one request after authentication and the route's role or admin check. Session-capable routes, including `/api/v1/me`, spend one after authentication but before any route-specific session check. Authenticated `/mcp` requests spend one before any tool-specific role check. A request refused with `401`, or with `403` by an ordinary REST role or admin check, doesn't normally spend the allowance.
One exception applies to successfully authenticated API keys while their bounded cache entry remains. A later request that enters a registered, Bearer-authenticated `/api/v1` route or mounted subtree is charged before authentication and authorization. A cache entry expires five minutes after the key's last successful authentication, but it can be evicted earlier. Therefore, a later `401` or `403` can still spend one request. If the allowance is exhausted, the request gets `429` before authentication. An unmatched path isn't precharged. `GET /api/v1/events/stream` and `GET /api/v1/admin/events/stream` are not charged.
Webhook deliveries don't count against your allowance, because Monitive sends them.
## Per-endpoint limits
Most of these limits apply on top of the account allowance, so a request must fit inside both. The exceptions are `GET /api/v1/events/stream` and `GET /api/v1/admin/events/stream`: they don't spend the account allowance, so only their own stream caps apply.
- **`POST /api/v1/monitors`**: 20 per minute per account, on top of the 200. Going over it returns `429` with `Retry-After` and `monitor creation rate limit exceeded; retry in s`.
- **`POST /api/v1/monitors/{id}/test`**: 1 every 10 seconds per monitor. Going over it returns `429` with `Retry-After` and `too many tests for this monitor; retry in s`.
- **`POST /api/v1/monitors/{id}/test`**: 600 checks per minute against one registrable domain, across all accounts. The limit is counted per domain. Going over it returns `429` with `Retry-After` and `domain rate limit exceeded; retry in s`.
- **`POST /api/v1/events/ticket`**: 20 per minute per credential: the API key, or the user for a session or OAuth token. Going over it returns `429` with `Retry-After` and `ticket rate limit exceeded`.
- **`GET /api/v1/events/stream`** and **`GET /mcp`**: 10 open streams at once per credential, shared between the two. A refusal returns `429` with `max concurrent stream connections reached (10); REST event streams and MCP streams share this limit per API key` and no `Retry-After`.
- **`POST /api/v1/admin/events/ticket`** (Monitive admin users only): 10 per minute per admin user. Going over it returns `429` with `Retry-After` and `ticket rate limit exceeded`.
- **`GET /api/v1/admin/events/stream`** (Monitive admin users only): 5 open streams at once per admin user. A refusal returns `429` with `max concurrent connections reached` and no `Retry-After`.
- **`POST /api/v1/recipients/{id}/test`**: 1 per minute per recipient. Going over it returns `429` with `Retry-After` and `too many test requests for this recipient; retry later`.
- **`POST /api/v1/recipients`** for an email recipient, **`PATCH /api/v1/recipients/{id}`** that changes the address, and **`POST /api/v1/recipients/{id}/confirm/resend`**: Confirmation emails are limited to 5 per hour per address, 20 per hour per account, and 300 per hour in one API process. The limits are counted per address, account, and API process. Going over a limit returns `429` with `Retry-After` and `too many confirmation emails; retry later` on create and patch, or `too many confirmation resends; retry later` on resend.
- **`POST /api/v1/recipients/{id}/confirm/resend`**: 1 every 60 seconds per recipient, counted from the last confirmation email to that recipient and separate from the hourly quotas above. Going over it returns `429` with `Retry-After` and `resend requested too recently`.
When Google or Microsoft sign-up creates a pending default email recipient, its confirmation attempt shares the same address, account, and API-process quotas. If any quota is exhausted, sign-up continues without a `429`, Monitive suppresses the confirmation email, and the recipient stays pending.
Over MCP, `create_monitor` shares the 20-per-minute monitor-creation limit. Going over it returns a tool error with the same message, `monitor creation rate limit exceeded; retry in s`, not an HTTP `429`. That error has no `Retry-After` header; the message carries the wait.
A new monitor whose first check is held back by the per-domain cap shows `"last_check_skipped": "domain_rate_limited"`.
## New-domain limits
Two rolling allowances limit how many distinct registrable domains your account can target. A successful monitor creation counts its target. A monitor update counts only if it changes the monitor's `url` or `type`; updates to other fields don't count.
Monitive lowercases each host, removes trailing root dots, and uses the public suffix list to find its effective top-level domain plus one. For example, `api.example.com` and `status.example.com` both count as `example.com`. If that lookup fails for an IP address, a single-label host, or an unrecognized suffix, the normalized full host is the domain key.
Both allowances are inclusive. The 30-minute allowance normally follows your plan's monitor cap, but an account can have a custom domain allowance. The 24-hour allowance always follows the plan's monitor cap. See [Pricing](/pricing/) for plan limits.
| Window | Allowance |
|---|---|
| Rolling 30 minutes | The same as your plan's monitor cap, unless your account has a custom domain allowance |
| Rolling 24 hours | Twice your plan's monitor cap |
Over REST, going over either allowance returns `429 Too Many Requests`. The rate-limit headers have the following values, where `` is the controlling allowance, `` is `1800` or `86400`, and `` is the number of seconds to wait:
```
Retry-After:
X-RateLimit-Reason: host_fan
X-RateLimit-Window:
X-RateLimit-Limit:
```
The response omits `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Its body is:
```
{"error":"too many distinct domains in a rolling window; slow monitor creation or target changes and retry","limit":,"window_seconds":,"retry_after_seconds":}
```
Your account is not suspended. Wait for `Retry-After`, then retry.
Over MCP, `create_monitor` and target-changing `update_monitor` calls return a tool error instead of an HTTP `429`. The exact message is `too many distinct domains in a rolling window; slow monitor creation or target changes and retry in seconds (limit: domains per s)`. A tool error has no HTTP rate-limit headers.
## Public endpoints
These limits are counted per token, email address, or IP address, never per account. Every refusal is a `429` with `Retry-After`.
- **`GET /feed/{token}`** and **`GET /feed/{token}/rss`**: 20 per minute per feed token. Every request counts. A refusal returns `too many requests; retry in s`.
- **`GET /ack/{token}`**: 60 per hour per IP address, separate from `POST /ack/{token}`. Every request counts. A refusal returns `too many requests; retry later`.
- **`POST /ack/{token}`**: 60 per hour per IP address, separate from `GET /ack/{token}`. Every request counts. A refusal returns `too many requests; retry later`.
- **`POST /oauth/email/start`**: 5 per hour per email address, 20 per hour per IP address, and 300 per hour across all callers. Every request counts. A refusal returns `too many sign-in requests; retry later`.
- **`POST /oauth/email/verify`**: 30 per hour per IP address and 600 per hour across all callers. Every request counts. A refusal returns `too many sign-in attempts from this address; retry later` per IP or `too many sign-in attempts; retry later` across all callers.
- **`GET`** and **`POST /email/confirm/{token}`**: 60 per hour per IP address, one allowance shared by `GET` and `POST`. Every request counts. A refusal returns `too many requests; retry later`.
- **`GET /email/unsubscribe/{token}`**: 60 per hour per IP address, with its own allowance. Every request counts. A refusal returns `too many requests; retry later`.
- **`GET /email/reports/{type}/unsubscribe/{token}`**: 60 per hour per IP address, with its own allowance. Every request counts. A refusal returns `too many requests; retry later`.
- **`POST /email/unsubscribe/{token}`**: 60 per hour per IP address and 300 per hour across all callers. Only malformed or unknown tokens count; a valid unsubscribe never counts. Once either allowance runs out, every unsubscribe `POST` from that IP address, or from anyone for the allowance across all callers, is refused until it refills. A refusal returns `too many requests; retry later`.
- **`POST /email/reports/{type}/unsubscribe/{token}`**: 60 per hour per IP address and 300 per hour across all callers, separate from the recipient-unsubscribe allowances. Only an unknown report type, or a malformed or unknown token, counts; the same refusal rule as the preceding bullet applies. A refusal returns `too many requests; retry later`.
- **`POST /oauth2/register`**: 10 per hour per IP address and 100 per hour across all callers. Every request counts. A refusal returns `too many client registrations from this address; retry later` per IP or `too many client registrations; retry later` across all callers, in the RFC 7591 body shape.
Linking an email sign-in from the dashboard, through `POST /api/v1/me/identities/email/start` and `POST /api/v1/me/identities/email/verify`, uses the same sign-in limits.
## Count limits
These caps limit how many of something an account or account member holds. The non-GET-monitor and API-key caps return `409 Conflict` over REST, not `429`. Waiting doesn't clear them; you have to remove one first. The browser push-subscription cap returns no error: a new subscription replaces that account member's oldest one.
| What | Cap | REST response | MCP response |
|---|---|---|---|
| Monitors with a non-GET `http_method`, disabled ones included | 5 per account | `409` with `non-GET monitor limit reached (max 5 per account)` | `create_monitor` and `update_monitor` return a tool error with the same text |
| API keys | 10 per account | `409` with `key limit reached`, on create and on rotate | `rotate_api_key` returns a tool error, `key limit reached` |
| Browser push subscriptions | 20 per account member | No error. A new subscription replaces that account member's oldest one. | None; there is no MCP tool |
Your plan's monitor count is listed on [Pricing](/pricing/).
Browser push delivery has a separate limit of one push fan-out per monitor in each five-minute window. After Monitive starts a fan-out, it suppresses browser-push fan-outs for later state transitions on that monitor during the rest of the window. This asynchronous suppression has no HTTP response and doesn't fail an API request.
## Alert email cap
By default, Monitive sends at most 1,000 alert emails per account per UTC day. All of the account's email recipients share the count.
An alert email over the cap isn't sent. Its row in `GET /api/v1/webhook-deliveries` has `status` set to `failed`, `last_response_code` set to `0`, and `response_body` set to `daily email cap reached`. No API request fails because of this cap.
## Response headers
Except for a new-domain `429`, responses to requests charged by the account allowance carry three `X-RateLimit-*` headers, on successes and on its `429`s alike. This includes authenticated `/mcp` requests, most `/api/v1` requests after authentication and authorization, and session-capable `/api/v1` routes that are charged before their route-specific session check. It also includes a cached API key's `401` or `403` response when the request was precharged.
```
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1681310460
```
| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | The allowance size, `200`. |
| `X-RateLimit-Remaining` | Requests left after this one. |
| `X-RateLimit-Reset` | The Unix time, in seconds, when the allowance is **full** again. It is not when your next request is allowed. |
A successful `POST /api/v1/monitors` carries the 200 allowance. A `429` from the monitor-creation limit replaces all three values with that limit's own, so `X-RateLimit-Limit` reads `20`. Concurrent-stream refusals on `GET /mcp` don't change the three headers.
A new-domain `429` doesn't carry the trio. It sets `X-RateLimit-Limit` to the controlling domain allowance, adds `X-RateLimit-Reason: host_fan` and `X-RateLimit-Window`, and removes `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
These responses never reach the account allowance and don't carry the `X-RateLimit-*` headers: `GET /api/v1/events/stream`, `GET /api/v1/admin/events/stream`, and every public endpoint under `/feed/*`, `/oauth/*`, `/oauth2/*`, `/email/*`, and `/ack/*`. Don't infer header behavior from a `401` or `403` status alone. A `401` or `403` carries the headers if the request was already charged, such as when a cached API key is precharged or a session-capable route is charged before its session check. Otherwise, the headers are absent.
`Retry-After` is a separate header. It is sent on a `429` only, as whole seconds to wait. It appears on every `429` on this page, authenticated or public, including the endpoints that never carry the `X-RateLimit-*` headers. It does not appear on the concurrent-stream refusals: `GET /api/v1/events/stream`, `GET /mcp`, and `GET /api/v1/admin/events/stream`. On a `429`, use `Retry-After`, not `X-RateLimit-Reset`.
## Handling 429 responses
Wait `Retry-After` seconds, then retry. The value is a whole number, at least `1`. On `POST /api/v1/monitors/{id}/test` and `/feed/{token}`, the value is rounded down, so add a second.
Treat every `429` as temporary. On an HTTP `429`, read the delay from `Retry-After`, not from the message.
Apart from the new-domain limits, `429`s on `/api/v1/*`, `/feed/*`, `/oauth/email/*`, `/email/*`, and `/ack/*` use the flat error envelope:
```json
{"error": "account rate limit exceeded; retry in 12s"}
```
```
Retry-After: 12
```
`/mcp` returns a JSON-RPC error:
```json
{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"account rate limit exceeded; retry in 12s"}}
```
`/oauth2/register` uses the RFC 7591 shape:
```json
{"error":"too_many_requests","error_description":"too many client registrations from this address; retry later"}
```
Four cases work differently:
- **New-domain limits.** A REST `429` from the new-domain limits can carry more fields than `error`. Don't parse the body for the wait; use `Retry-After`.
- **Concurrent-stream caps.** `GET /api/v1/events/stream`, `GET /mcp`, and `GET /api/v1/admin/events/stream` return `429` with no `Retry-After`. Close one of your streams, or wait for one to end, before you open another. The ticket isn't spent, so you can retry with it.
- **MCP tool errors.** Over MCP, the monitor-creation limit, the new-domain limits, the non-GET-monitor cap, and the API-key cap come back as a tool error inside a successful HTTP response, not as an HTTP `429` or `409`. A tool error has no headers. For the monitor-creation limit, the message says how many seconds to wait.
- **Count limits.** The non-GET-monitor and API-key caps return `409`, not `429`. Waiting doesn't help; remove one first. The browser push-subscription cap returns no error; the oldest subscription is replaced.
For the error envelope and other status codes, see [Errors](/docs/errors/#429-too-many-requests).
## What suspends an account
No rate limit or count limit suspends your account, and repeated `429`s don't make the wait longer.
Two security checks do suspend an account:
- **Port scanning.** Creating monitors, or changing a monitor's `url` or `type`, so that 6 or more distinct ports on at most 2 hosts are targeted within 10 minutes. Ports used by TCP monitors count against a higher threshold of 12. The account is suspended and its monitors are removed.
- **DNS rebinding.** A monitored hostname that later resolves to a blocked address. The re-check that runs every 5 minutes catches it.
A suspended account gets `403` with `account suspended; contact support` on authenticated requests.
---
# Security and target restrictions
> Monitive is designed for public uptime checks, not network scanning.
## Private/reserved IP blocking
Targets that resolve to private, reserved, or loopback IP ranges are blocked:
- `10.0.0.0/8`
- `172.16.0.0/12`
- `192.168.0.0/16`
- `127.0.0.0/8`
- `169.254.0.0/16` (link-local)
- `::1`, `fc00::/7`, `fe80::/10`
```json
{
"error": "url rejected: ip 10.0.0.5 is in a blocked range"
}
```
The full error envelope is documented in [Errors](/docs/errors/).
DNS resolution is cached and re-validated — SSRF via DNS rebinding is blocked.
## Disallowed target classes
- Private and reserved IPs (see above)
- Targets on non-standard ports for TCP monitors (restricted to common service ports)
- Targets that actively opt out (see below)
## Port restrictions for TCP monitors
TCP monitors are restricted to a small allowlist of common HTTP-style service ports to prevent the platform being repurposed as a port scanner. The full allowlist is:
`80`, `443`, `8080`, `8443`, `3000`, `5000`, `8000`, `8888`
Any other port returns `400` with an error message naming the allowed set. Database ports (`3306`, `5432`, `6379`, `27017`), message-queue ports (`5672`, `9092`), and admin-style ports (`22`, `25`, `53`, `110`, `143`, `993`, `995`) are intentionally **not** on the list.
## URL validation
All monitor URLs are validated as UTF-8 strings with no null bytes (`U+0000`) and no ASCII control characters (`U+0000`–`U+001F` and `U+007F`). Violations return `400` before the SSRF guard runs.
## Rate limiting and abuse controls
- 200 API requests per minute per account
- 50 monitors per account
- 10 API keys per account
- Exponential backoff on sustained-down monitors
- Flap detection collapses noisy state transitions
## Target owner opt-out
Target owners can request opt-out by contacting [hello@monitive.com](mailto:hello@monitive.com). Opted-out domains are blocked from being monitored.
To recognize Monitive's checks in your logs, or to allow them through Cloudflare or another firewall, see [Monitive bot](/bot/). It lists the User-Agent, the request signing headers, and the probe IP addresses.
---
# Examples
> Working code examples for every supported language and integration.
:::tip[Working examples repo]
Full runnable copies of every snippet on this page live at [github.com/uptimemonitoring/examples](https://github.com/uptimemonitoring/examples) — including self-contained scripts, GitHub Actions workflows, and webhook relay recipes.
:::
> The target hostname must resolve at creation time. The snippets below use `https://example.com/` because it actually resolves and returns 200 — fine for a smoke test. In real use, point at your own service (e.g. `https://api.your-domain.com/healthz`).
## curl
Create a monitor from any terminal:
```bash
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "api-prod",
"url": "https://example.com",
"type": "http"
}'
```
## Node.js
```js
const res = await fetch("https://api.monitive.com/api/v1/monitors", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MONITIVE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "api-prod",
url: "https://example.com",
type: "http",
}),
});
const data = await res.json();
console.log(`Monitor ${data.monitor.id} created, status: ${data.state.status}`);
```
## Python
```python
import os
import requests
resp = requests.post(
"https://api.monitive.com/api/v1/monitors",
headers={"Authorization": f"Bearer {os.environ['MONITIVE_API_KEY']}"},
json={
"name": "api-prod",
"url": "https://example.com",
"type": "http",
},
)
data = resp.json()
print(f"Monitor {data['monitor']['id']} created, status: {data['state']['status']}")
```
## GitHub Actions
### Post-deploy health gate
```yaml
name: Deploy and verify
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./deploy.sh
- name: Verify deploy health
uses: uptimemonitoring/assert-healthy@v1
with:
api-key: ${{ secrets.MONITIVE_API_KEY }}
monitor-ids: ${{ vars.MONITOR_ID }}
```
## Claude / Claude Code
```text
Add Monitive as an MCP server
Create a monitor for https://example.com/
Assert that it is healthy after deploy
```
MCP configuration:
```json
{
"mcpServers": {
"monitive": {
"url": "https://api.monitive.com/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
## Cursor
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"monitive": {
"url": "https://api.monitive.com/mcp",
"headers": {
"Authorization": "Bearer mk_live_..."
}
}
}
}
```
Then use natural language:
```text
Create a monitor for https://example.com/
and tell me if it is healthy
```
## Webhook recipients
Webhooks are account-level recipients — create one, then attach it to any number of monitors (see [Choose who gets alerts](/docs/guides/alert-recipients/)):
```bash
# Create a webhook recipient pointed at your own endpoint
curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"ops-webhook","type":"webhook","config":{"url":"https://hooks.example.com/incident"}}'
# -> {"id": 42, ..., "secret": "whs_live_…"}
# Read monitor 1287's current recipients before attaching the new one —
# PUT replaces the complete set, so skipping this step would detach
# every recipient already on the monitor
CURRENT=$(curl -s https://api.monitive.com/api/v1/monitors/1287/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY")
# -> {"recipients": [{"id": 10, "grace_s": 120}]}
# Build the full set from what the GET actually returned — the existing
# recipient plus the new one. Requires jq.
BODY=$(echo "$CURRENT" | jq '{recipients: (.recipients + [{id: 42, grace_s: 120}])}')
curl -X PUT https://api.monitive.com/api/v1/monitors/1287/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d "$BODY"
```
The HMAC secret is returned only in the recipient-creation response; store it for [signature verification](/docs/webhooks/#signature-verification). **This read-then-write sequence has no concurrency protection** — the `PUT` carries no version, ETag, or `If-Match` precondition, so a concurrent editor can silently overwrite your change. Edit a monitor's recipients from one place at a time, and re-read the result after saving to confirm it matches what you intended; see [Choose who gets alerts](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp) for the full warning.
A `type: "webhook"` recipient's payload isn't the shape Slack, Discord, Pushover, or ntfy expect. If you want Slack, create a native `type: "slack"` recipient instead — see the [Slack alerts guide](/docs/guides/slack-alerts/). For PagerDuty, create a native `type: "pagerduty"` recipient, which has full dashboard support — see [Send alerts to PagerDuty](/docs/guides/pagerduty-alerts/); for anything else with no native recipient type, use the open-source [alert-bridge](/docs/alert-bridge/) relay instead of pointing a webhook recipient's URL directly at it.
---
# FAQ
> Common questions about Monitive.
## Is it really free
Yes. The free plan includes 50 monitors, checked every minute, with 30 days of incident history.
## Do I need to type in an email address
Sign in with GitHub, Google, Microsoft, or email. With GitHub or Google, neither provider has you type in an address. Email sign-in is the exception: you enter one directly. GitHub sign-in still needs a verified primary email on GitHub's side regardless of what you type — sign-in fails outright if GitHub reports none, or only an unverified one. We normally store whatever address GitHub returns as your account's email, the same as a direct email sign-in — except we skip saving it if your account already has an email on file, or if that address already belongs to a different account. Google sign-in needs no email address you separately enter or that we store — Google's authorization response includes a verified address, which we use transiently for trusted-domain checks and to match it against existing accounts for linking purposes, but the address value itself is not persisted. And recipients for alerts can be webhooks instead of email. See the [sign-in guide](/docs/guides/sign-in/).
## How do alerts reach me
Webhooks, browser push, email, RSS feeds, and MCP queries. See [Webhooks](/docs/webhooks/), [Push notifications](/docs/push-notifications/), and the [email alerts guide](/docs/guides/email-alerts/).
## How do you avoid false positives
Infrastructure-class failures are re-checked from two additional regions. State only changes when 2 of 3 regions agree. See [Monitors](/docs/monitors/) for details on cross-region confirmation.
## Can I use this in GitHub Actions
Yes — the `uptimemonitoring/assert-healthy` action is built for deploy verification. See [GitHub Action](/docs/github-action/).
## Can I monitor private IPs or internal services
No. Private and reserved targets are blocked. See [Security](/docs/security/) for details on target restrictions.