Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
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.mdxindex 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 noEvery 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 logdiff --git a/apps/docs/src/content/docs/reference/notification.mdx b/apps/docs/src/content/docs/reference/notification.mdxindex 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 Schemadiff --git a/apps/docs/src/content/docs/sdk/nodejs/index.mdx b/apps/docs/src/content/docs/sdk/nodejs/index.mdxindex 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 KeyBefore 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.mdxindex 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 NotificationVerify a notification configuration without creating a channel.