Skip to content

Open-source status page, incident response and uptime monitoring

docs: fix docs vs code discrepancies (#2227)

Colin Ozanne2aee90a0e9c6
diff --git a/apps/docs/src/content/docs/reference/mcp-server.mdx b/apps/docs/src/content/docs/reference/mcp-server.mdx
index bbf90d1aa..e7165470c 100644
--- a/apps/docs/src/content/docs/reference/mcp-server.mdx
+++ b/apps/docs/src/content/docs/reference/mcp-server.mdx
@@ -27,7 +27,7 @@ Get a key from the dashboard's **Settings → API Tokens**.
Each API key carries a scope that controls what tools the MCP server exposes:
-- **Read-only** — the server only registers `list_*` tools. Mutation tools (`create_*`, `update_*`, `add_*`, `resolve_*`) are not advertised in `tools/list` and cannot be called.
+- **Read-only** — the server only registers read tools (`list_*` and `get_*`). Mutation tools (`create_*`, `update_*`, `add_*`, `resolve_*`) are not advertised in `tools/list` and cannot be called.
- **Read & write** — every tool is available.
Scope is set at key creation time and is **immutable**. To change a key's scope, revoke it and issue a new one.
@@ -36,19 +36,57 @@ For AI agents that should only observe state — health summaries, paging on-cal
## Tools
-The server exposes 9 tools, scoped to the workspace tied to your API key. Mutations write to the audit log with `metadata.transport = "mcp"`.
+The server exposes 18 tools, grouped by resource and scoped to the workspace tied to your API key. Mutations write to the audit log with `actor_type = "mcp"` (see [Audit log](#audit-log)).
+
+### Pages
+
+| Tool | Type | Purpose |
+|------------------------|------|---------|
+| `list_status_pages` | read | List public status pages with their slug and id. Used to discover the `pageId` required by mutation tools. |
+| `list_page_components` | read | List components on a status page with their id, name, type (`monitor` / `static`), and linked monitor. Used to discover the `pageComponentIds` accepted by `create_status_report`, `update_status_report`, and `create_maintenance`. |
+
+### Status reports
| Tool | Type | Purpose |
|----------------------------|----------|---------|
-| `list_status_pages` | read | List public status pages with their slug and id. Used to discover the `pageId` required by mutation tools. |
-| `list_page_components` | read | List components on a status page with their id, name, type (`monitor` / `static`), and linked monitor. Used to discover the `pageComponentIds` accepted by `create_status_report`, `update_status_report`, and `create_maintenance`. |
| `list_status_reports` | read | List status reports newest-first. `filter: "active" \| "all"` (defaults to active = excludes resolved). Paginated via `page` (1-indexed) and `perPage`; response carries a `pagination` object with `page`, `perPage`, `totalSize`, and `totalPages`. |
-| `list_maintenances` | read | List maintenance windows newest-first. Paginated via `page` (1-indexed) and `perPage`; response carries a `pagination` object with `page`, `perPage`, `totalSize`, and `totalPages`. |
| `create_status_report` | mutation | Create a new status report on a status page with an initial public update. |
| `add_status_report_update` | mutation | Append a public update to an existing status report and bump its status. |
| `update_status_report` | mutation | Edit a report's title, status, or affected components without posting a public update. |
| `resolve_status_report` | mutation | Mark a report resolved and post a final public update with the supplied message. |
-| `create_maintenance` | mutation | Schedule a maintenance window (`from` / `to` are ISO 8601 strings). |
+
+### Maintenance
+
+| Tool | Type | Purpose |
+|----------------------|----------|---------|
+| `list_maintenances` | read | List maintenance windows newest-first. Paginated via `page` (1-indexed) and `perPage`; response carries a `pagination` object with `page`, `perPage`, `totalSize`, and `totalPages`. |
+| `create_maintenance` | mutation | Schedule a maintenance window (`from` / `to` are ISO 8601 strings). |
+
+### Monitors
+
+| Tool | Type | Purpose |
+|-----------------------|------|---------|
+| `list_monitors` | read | List monitors newest-first, including `activeIncidentCount`. Used to discover the numeric `monitorId` the other monitor tools require. |
+| `get_monitor` | read | Full configuration for one monitor: URL, regions, periodicity, retry/timeout, notification channels, tags. Does not return latency or status. |
+| `get_monitor_status` | read | Per-region current health (active / degraded / error). No time window. |
+| `get_monitor_summary` | read | Aggregate success/degraded/error counts, p50–p99 latency, and `lastPingAt` over `1d` (default), `7d`, or `14d`. |
+| `list_response_logs` | read | Recent per-region HTTP check results — request status, status code, latency — over `1d` (default), `7d`, or `14d`. HTTP monitors only; `limit` ≤ 100. |
+| `get_response_log` | read | Full detail of one check: URL, timing breakdown (dns/connect/tls/ttfb/transfer), redacted response headers, error message, assertion results. |
+
+### Notifications
+
+| Tool | Type | Purpose |
+|----------------------|------|---------|
+| `list_notifications` | read | List notification channels and the monitors each one is wired to. Channel credentials are never exposed. |
+
+### Audit
+
+Registered only when the workspace plan includes the `audit-log` feature — otherwise these tools are absent from `tools/list`.
+
+| Tool | Type | Purpose |
+|-------------------|------|---------|
+| `list_audit_logs` | read | List audit-log entries (mutating actions) newest-first, bounded to the last 14 days. Optional `entityType` + `entityId` filter. |
+| `get_audit_log` | read | Full before/after snapshots and `changedFields` for a single audit-log entry. |
The MCP client gates every tool call behind your approval — the server does not gate again. Each tool also carries [MCP annotations](https://modelcontextprotocol.io/specification/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so well-behaved clients can decide whether to confirm, cache, or surface differently.
@@ -56,6 +94,8 @@ The MCP client gates every tool call behind your approval — the server does no
Every mutation tool has a **required** `notify: boolean` field — there is no default. The tool's input schema rejects calls that omit it, which forces the LLM to make an explicit choice (and therefore ask the user) before firing.
+This required-field behaviour is specific to MCP. The dashboard AI assistant and the Slack agent wrap these same tools in an approval step that strips `notify` from the model-facing schema and injects it from a human toggle defaulting to `false`. MCP exposes the raw schema, so the caller must supply `notify` explicitly.
+
Notifications dispatch as part of the same call. There is no separate notify tool: if you create a status report or append an update with `notify: false`, that update will **never** reach subscribers — you cannot retroactively notify the same update later. This matches the dashboard and Slack agent semantics.
The mutation and the notify dispatch are sequential, not transactional. The mutation persists first; if the notify step then throws (transient provider issue, partial outage of an integration), the response carries `notified: false` and the row stays.
@@ -140,6 +180,7 @@ Error messages are not redacted — the consumer is an LLM that benefits from th
## Limits
- `list_status_reports` and `list_maintenances` use offset pagination: `page` (1-indexed, default 1) and `perPage` (default 50, max 200). The response's `pagination.totalPages` tells the LLM whether more pages exist. `list_status_pages` is unpaginated (workspaces typically have a handful).
+- `list_monitors` and `list_audit_logs` page via `perPage` (max 50); `list_notifications` via `perPage` (max 200); `list_response_logs` via `limit` (max 100) and `offset`.
- No per-key rate limiting today. Treat MCP usage like REST: one server call per tool invocation.
## Audit log
diff --git a/apps/docs/src/content/docs/reference/notification.mdx b/apps/docs/src/content/docs/reference/notification.mdx
index 49b9375c5..c5c67aba4 100644
--- a/apps/docs/src/content/docs/reference/notification.mdx
+++ b/apps/docs/src/content/docs/reference/notification.mdx
@@ -86,13 +86,9 @@ Sends HTTP POST requests to a custom endpoint with a JSON payload.
- **URL:** (Required) The endpoint URL to which the webhook payload will be sent.
- **Headers:** (Optional) Custom HTTP headers to include with the webhook request (key-value pairs).
-#### Notification Payloads
+#### Notification Payload
-Webhook notifications utilize specific JSON payloads for different monitor status changes.
-
-##### Monitor Recovery Payload
-
-Sent when a monitor recovers from a `degraded` or `error` state.
+Every webhook notification — `error`, `degraded`, and `recovered` — uses the same flat JSON payload. `statusCode`, `latency`, and `errorMessage` are optional on **every** status; the sender includes whichever apply to the check.
```json
{
@@ -102,51 +98,29 @@ Sent when a monitor recovers from a `degraded` or `error` state.
"url": "http://openstat.us"
},
"cronTimestamp": 1744023705307,
- "status": "recovered",
- "statusCode": 200,
- "latency": 1337
+ "status": "error",
+ "statusCode": 500,
+ "latency": 1337,
+ "errorMessage": "Internal Server Error"
}
```
**Payload Fields:**
-| Field | Type | Description |
-| :------------ | :------- | :------------------------------------------------------------------- |
-| `monitor.id` | `number` | Unique identifier of the monitor. |
-| `monitor.name`| `string` | Name of the monitor. |
-| `monitor.url` | `string` | The URL or URI being monitored. |
-| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
-| `status` | `string` | Indicates the monitor status: `"recovered"`. |
-| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |
-| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |
-
-##### Monitor Failure Payload
-
-Sent when a monitor enters an `error` or `degraded` state.
-
-```json
-{
- "monitor": {
- "id": 1,
- "name": "test",
- "url": "http://openstat.us"
- },
- "cronTimestamp": 1744023705307,
- "status": "error",
- "errorMessage": "Connection refused"
-}
-```
+| Field | Type | Description |
+| :------------- | :------- | :------------------------------------------------------------------- |
+| `monitor.id` | `number` | Unique identifier of the monitor. |
+| `monitor.name` | `string` | Name of the monitor. |
+| `monitor.url` | `string` | The URL or URI being monitored. |
+| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
+| `status` | `string` | Monitor status: `"degraded"`, `"error"`, or `"recovered"`. |
+| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |
+| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |
+| `errorMessage` | `string` | (Optional) A description of the error encountered during the check. |
-**Payload Fields:**
+#### Authentication
-| Field | Type | Description |
-| :------------ | :------- | :------------------------------------------------------------------- |
-| `monitor.id` | `number` | Unique identifier of the monitor. |
-| `monitor.name`| `string` | Name of the monitor. |
-| `monitor.url` | `string` | The URL or URI being monitored. |
-| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
-| `status` | `string` | Indicates the monitor status: `"degraded"` or `"error"`. |
-| `errorMessage`| `string` | (Optional) A description of the error encountered during the check. |
+Webhook requests carry **no payload signature or HMAC**. The only verification mechanism is the custom headers you configure (e.g. a shared-secret header such as `Authorization` or `x-webhook-secret`) — validate one of those on your endpoint.
#### Zod Schema
diff --git a/apps/docs/src/content/docs/sdk/nodejs/index.mdx b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
index 345fa0d09..ad7ca324e 100644
--- a/apps/docs/src/content/docs/sdk/nodejs/index.mdx
+++ b/apps/docs/src/content/docs/sdk/nodejs/index.mdx
@@ -5,6 +5,8 @@ description: "Install and start using the openstatus Node.js SDK"
import { Aside } from '@astrojs/starlight/components';
+The SDK is open source and developed in its own repository, [openstatusHQ/sdk-node](https://github.com/openstatusHQ/sdk-node) (separate from the main monorepo).
+
## Get Your API Key
Before using the SDK, you need an API key:
diff --git a/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx b/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx
index a84d4db2f..d342b3b6a 100644
--- a/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx
+++ b/apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx
@@ -255,6 +255,8 @@ const { notification } = await client.notification.v1.NotificationService
});
```
+See the [webhook payload reference](/reference/notification#webhook) for the exact JSON your endpoint receives, the optional fields, and how to authenticate requests.
+
## Send Test Notification
Verify a notification configuration without creating a channel.