Skip to content

Commit 058d421

Browse files
finxolfinxol
committed
docs: fix docs vs code discrepancies
1 parent 559fc67 commit 058d421

4 files changed

Lines changed: 69 additions & 50 deletions

File tree

‎apps/docs/src/content/docs/reference/mcp-server.mdx‎

Lines changed: 47 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Get a key from the dashboard's **Settings → API Tokens**.
2727

2828
Each API key carries a scope that controls what tools the MCP server exposes:
2929

30-
- **Read-only** — the server only registers `list_*` tools. Mutation tools (`create_*`, `update_*`, `add_*`, `resolve_*`) are not advertised in `tools/list` and cannot be called.
30+
- **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.
3131
- **Read & write** — every tool is available.
3232

3333
Scope is set at key creation time and is **immutable**. To change a key's scope, revoke it and issue a new one.
@@ -36,26 +36,66 @@ For AI agents that should only observe state — health summaries, paging on-cal
3636

3737
## Tools
3838

39-
The server exposes 9 tools, scoped to the workspace tied to your API key. Mutations write to the audit log with `metadata.transport = "mcp"`.
39+
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 `metadata.transport = "mcp"`.
40+
41+
### Pages
42+
43+
| Tool | Type | Purpose |
44+
|------------------------|------|---------|
45+
| `list_status_pages` | read | List public status pages with their slug and id. Used to discover the `pageId` required by mutation tools. |
46+
| `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`. |
47+
48+
### Status reports
4049

4150
| Tool | Type | Purpose |
4251
|----------------------------|----------|---------|
43-
| `list_status_pages` | read | List public status pages with their slug and id. Used to discover the `pageId` required by mutation tools. |
44-
| `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`. |
4552
| `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`. |
46-
| `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`. |
4753
| `create_status_report` | mutation | Create a new status report on a status page with an initial public update. |
4854
| `add_status_report_update` | mutation | Append a public update to an existing status report and bump its status. |
4955
| `update_status_report` | mutation | Edit a report's title, status, or affected components without posting a public update. |
5056
| `resolve_status_report` | mutation | Mark a report resolved and post a final public update with the supplied message. |
51-
| `create_maintenance` | mutation | Schedule a maintenance window (`from` / `to` are ISO 8601 strings). |
57+
58+
### Maintenance
59+
60+
| Tool | Type | Purpose |
61+
|----------------------|----------|---------|
62+
| `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`. |
63+
| `create_maintenance` | mutation | Schedule a maintenance window (`from` / `to` are ISO 8601 strings). |
64+
65+
### Monitors
66+
67+
| Tool | Type | Purpose |
68+
|-----------------------|------|---------|
69+
| `list_monitors` | read | List monitors newest-first, including `activeIncidentCount`. Used to discover the numeric `monitorId` the other monitor tools require. |
70+
| `get_monitor` | read | Full configuration for one monitor: URL, regions, periodicity, retry/timeout, notification channels, tags. Does not return latency or status. |
71+
| `get_monitor_status` | read | Per-region current health (active / degraded / error). No time window. |
72+
| `get_monitor_summary` | read | Aggregate success/degraded/error counts, p50–p99 latency, and `lastPingAt` over `1d` (default), `7d`, or `14d`. |
73+
| `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. |
74+
| `get_response_log` | read | Full detail of one check: URL, timing breakdown (dns/connect/tls/ttfb/transfer), redacted response headers, error message, assertion results. |
75+
76+
### Notifications
77+
78+
| Tool | Type | Purpose |
79+
|----------------------|------|---------|
80+
| `list_notifications` | read | List notification channels and the monitors each one is wired to. Channel credentials are never exposed. |
81+
82+
### Audit
83+
84+
Registered only when the workspace plan includes the `audit-log` feature — otherwise these tools are absent from `tools/list`.
85+
86+
| Tool | Type | Purpose |
87+
|-------------------|------|---------|
88+
| `list_audit_logs` | read | List audit-log entries (mutating actions) newest-first, bounded to the last 14 days. Optional `entityType` + `entityId` filter. |
89+
| `get_audit_log` | read | Full before/after snapshots and `changedFields` for a single audit-log entry. |
5290

5391
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.
5492

5593
### Notifying subscribers
5694

5795
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.
5896

97+
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.
98+
5999
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.
60100

61101
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
140180
## Limits
141181

142182
- `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).
183+
- `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`.
143184
- No per-key rate limiting today. Treat MCP usage like REST: one server call per tool invocation.
144185

145186
## Audit log

‎apps/docs/src/content/docs/reference/notification.mdx‎

Lines changed: 18 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -86,13 +86,9 @@ Sends HTTP POST requests to a custom endpoint with a JSON payload.
8686
- **URL:** (Required) The endpoint URL to which the webhook payload will be sent.
8787
- **Headers:** (Optional) Custom HTTP headers to include with the webhook request (key-value pairs).
8888

89-
#### Notification Payloads
89+
#### Notification Payload
9090

91-
Webhook notifications utilize specific JSON payloads for different monitor status changes.
92-
93-
##### Monitor Recovery Payload
94-
95-
Sent when a monitor recovers from a `degraded` or `error` state.
91+
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.
9692

9793
```json
9894
{
@@ -102,51 +98,29 @@ Sent when a monitor recovers from a `degraded` or `error` state.
10298
"url": "http://openstat.us"
10399
},
104100
"cronTimestamp": 1744023705307,
105-
"status": "recovered",
106-
"statusCode": 200,
107-
"latency": 1337
101+
"status": "error",
102+
"statusCode": 500,
103+
"latency": 1337,
104+
"errorMessage": "Internal Server Error"
108105
}
109106
```
110107

111108
**Payload Fields:**
112109

113-
| Field | Type | Description |
114-
| :------------ | :------- | :------------------------------------------------------------------- |
115-
| `monitor.id` | `number` | Unique identifier of the monitor. |
116-
| `monitor.name`| `string` | Name of the monitor. |
117-
| `monitor.url` | `string` | The URL or URI being monitored. |
118-
| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
119-
| `status` | `string` | Indicates the monitor status: `"recovered"`. |
120-
| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |
121-
| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |
122-
123-
##### Monitor Failure Payload
124-
125-
Sent when a monitor enters an `error` or `degraded` state.
126-
127-
```json
128-
{
129-
"monitor": {
130-
"id": 1,
131-
"name": "test",
132-
"url": "http://openstat.us"
133-
},
134-
"cronTimestamp": 1744023705307,
135-
"status": "error",
136-
"errorMessage": "Connection refused"
137-
}
138-
```
110+
| Field | Type | Description |
111+
| :------------- | :------- | :------------------------------------------------------------------- |
112+
| `monitor.id` | `number` | Unique identifier of the monitor. |
113+
| `monitor.name` | `string` | Name of the monitor. |
114+
| `monitor.url` | `string` | The URL or URI being monitored. |
115+
| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
116+
| `status` | `string` | Monitor status: `"degraded"`, `"error"`, or `"recovered"`. |
117+
| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |
118+
| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |
119+
| `errorMessage` | `string` | (Optional) A description of the error encountered during the check. |
139120

140-
**Payload Fields:**
121+
#### Authentication
141122

142-
| Field | Type | Description |
143-
| :------------ | :------- | :------------------------------------------------------------------- |
144-
| `monitor.id` | `number` | Unique identifier of the monitor. |
145-
| `monitor.name`| `string` | Name of the monitor. |
146-
| `monitor.url` | `string` | The URL or URI being monitored. |
147-
| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
148-
| `status` | `string` | Indicates the monitor status: `"degraded"` or `"error"`. |
149-
| `errorMessage`| `string` | (Optional) A description of the error encountered during the check. |
123+
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.
150124

151125
#### Zod Schema
152126

‎apps/docs/src/content/docs/sdk/nodejs/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: "Install and start using the openstatus Node.js SDK"
55

66
import { Aside } from '@astrojs/starlight/components';
77

8+
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).
9+
810
## Get Your API Key
911

1012
Before using the SDK, you need an API key:

‎apps/docs/src/content/docs/sdk/nodejs/notification-service.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,8 @@ const { notification } = await client.notification.v1.NotificationService
255255
});
256256
```
257257

258+
See the [webhook payload reference](/reference/notification#webhook) for the exact JSON your endpoint receives, the optional fields, and how to authenticate requests.
259+
258260
## Send Test Notification
259261

260262
Verify a notification configuration without creating a channel.

0 commit comments

Comments
 (0)