Skip to content

Open-source status page, incident response and uptime monitoring

docs: fix docs accuracy (#2675)

Thibault Le Ouaya343cdea551c
diff --git a/apps/web/src/content/pages/docs/guides/getting-started.mdx b/apps/web/src/content/pages/docs/guides/getting-started.mdx
index 44e3bbb30..e7bcf7789 100644
--- a/apps/web/src/content/pages/docs/guides/getting-started.mdx
+++ b/apps/web/src/content/pages/docs/guides/getting-started.mdx
@@ -30,7 +30,7 @@ Our how-to guides solve specific problems with step-by-step instructions, walk y
## Agents and team workflow
-- **[Connect openstatus to Claude Code](/docs/guides/how-to-connect-openstatus-to-claude-code)** — give a coding agent access through the MCP server.
+- **[Connect openstatus to your coding agent](/docs/guides/how-to-connect-openstatus-to-your-agent)** — give Claude Code, Codex, opencode, Cursor, or ChatGPT access through the MCP server.
- **[Set up the Slack agent](/docs/guides/how-to-setup-slack-agent)** — manage incidents from Slack in natural language.
- **[Set up SAML single sign-on](/docs/guides/how-to-set-up-saml-sso)** — let your team sign in through your identity provider.
diff --git a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
index 714bc823f..56b8dccf5 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx
@@ -93,6 +93,7 @@ Pick a theme under **Settings > Appearance**, in the **Style** field. The shippe
- `passbolt`
- `gruvbox`
- `tomorrow`
+- `probo`
Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. You can also [create and contribute your own](/docs/guides/how-to-create-status-page-theme).
diff --git a/apps/web/src/content/pages/docs/guides/how-to-create-private-location.mdx b/apps/web/src/content/pages/docs/guides/how-to-create-private-location.mdx
index a3b3f70f4..5e9aa05b8 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-create-private-location.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-create-private-location.mdx
@@ -83,7 +83,11 @@ docker logs openstatus-probe
Common causes:
- **Invalid token** — double-check the token value; ensure no extra spaces or newlines.
-- **Wrong variable name** — the probe reads `OPENSTATUS_KEY`. `OPENSTATUS_TOKEN` is ignored, so the probe starts unauthenticated and fetches no monitors.
+- **Wrong variable name** — the probe reads `OPENSTATUS_KEY` and nothing else. If you set
+ `OPENSTATUS_TOKEN` instead, the probe refuses to start and exits immediately with:
+ ```
+ OPENSTATUS_KEY is required: the probe cannot authenticate against openstatus
+ ```
- **Network issues** — ensure the container can reach `openstatus-private-location.fly.dev` on port 443.
### No data appearing in the dashboard
diff --git a/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx b/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx
index 32c7d4b65..f8241ae07 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx
@@ -125,7 +125,7 @@ Your private location probe is now running on Cloudflare Containers and will sta
## Verify the deployment
-You can check the logs of your Cloudflare Worker to see the probe in action. In your openstatus dashboard, the private location should now show as connected.
+You can check the logs of your Cloudflare Worker to see the probe in action. In your openstatus dashboard, the private location's status flips to **active** once the agent reports, and checks from it start appearing in your monitors' response logs.
<Image
src="/docs/guides/how-to-deploy-probes-cf-containters/cloudflare-log.png"
@@ -135,6 +135,6 @@ You can check the logs of your Cloudflare Worker to see the probe in action. In
<Image
src="/docs/guides/how-to-deploy-probes-cf-containters/private-location.jpg"
- alt="openstatus Private Location connected"
- caption="The private location showing as 'Connected' in the openstatus dashboard."
+ alt="openstatus monitor response logs showing checks from a private location"
+ caption="Response logs for a monitor, showing checks arriving from the private probe (Cloud Provider: private)."
/>
diff --git a/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx b/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx
index 3b1e9bada..db3d1661e 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx
@@ -11,13 +11,13 @@ You want to analyze your openstatus monitoring data alongside other telemetry da
## Solution
-openstatus can export monitoring metrics to any OTLP (OpenTelemetry Protocol) compatible endpoint. By adding a simple configuration to your `openstatus.yaml` file, you can have metrics from every check sent directly to your monitoring stack.
+openstatus can export monitoring metrics to any OTLP (OpenTelemetry Protocol) compatible endpoint. Add an `open_telemetry` block to a monitor in your Terraform configuration and metrics from every check that monitor runs are sent straight to your monitoring stack.
## Prerequisites
- An observability platform that supports OTLP metric ingestion over HTTP.
-- An `openstatus.yaml` file to configure your monitors.
-- The [openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli) to apply your configuration.
+- A workspace on a plan that includes OTLP export (**Pro** and **Scale**).
+- Terraform and the [openstatus provider](/docs/reference/terraform) configured — see [Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform) if you have not set it up yet.
## Step-by-step guide
@@ -28,39 +28,86 @@ First, you need to find the specific URL and any required authentication headers
- **Endpoint URL** — look for an HTTP endpoint for OTLP metrics. It typically ends in `/v1/metrics`. For example: `https://otlp.your-provider.com/v1/metrics`.
- **Headers** — you will likely need an authentication header, such as `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`.
-### 2. Configure your `openstatus.yaml` file
-
-Open your `openstatus.yaml` file and add the `openTelemetry` block at the top level.
-
-```yaml
-# yaml-language-server: $schema=https://www.openstatus.dev/schema.json
-
-openTelemetry:
- endpoint: <YOUR_OTLP_ENDPOINT_URL>
- headers:
- Authorization: Bearer <YOUR_TOKEN>
- # Add any other required headers here
-
-# Your monitors are defined below
-my-first-monitor:
- # ...
+### 2. Add an `open_telemetry` block to your monitor
+
+`open_telemetry` is a block on the monitor resource, so each monitor declares its own export
+target. It is available on every monitor type — `openstatus_http_monitor`,
+`openstatus_tcp_monitor`, `openstatus_dns_monitor`, and `openstatus_icmp_monitor`.
+
+```terraform
+variable "otlp_token" {
+ type = string
+ sensitive = true
+}
+
+resource "openstatus_http_monitor" "api" {
+ name = "API Health Check"
+ url = "https://api.example.com/health"
+ periodicity = "1m"
+ active = true
+ regions = ["fly-iad", "fly-ams"]
+
+ open_telemetry {
+ endpoint = "https://otlp.your-provider.com/v1/metrics"
+
+ headers {
+ key = "Authorization"
+ value = "Bearer ${var.otlp_token}"
+ }
+ }
+}
```
-Replace `<YOUR_OTLP_ENDPOINT_URL>` and `<YOUR_TOKEN>` with the values you found in step 1.
+Mark the token `sensitive` and pass it in with `TF_VAR_otlp_token` or from a secrets manager
+rather than committing it.
**Note**: Currently, we only support OTLP over HTTP.
-### 3. Apply the configuration
+### 3. Share one endpoint across many monitors
+
+Because the block lives on each resource, put the endpoint and headers in a `locals` block and
+use `dynamic` so a change to the destination is a one-line edit rather than a sweep across every
+monitor:
+
+```terraform
+locals {
+ otlp_endpoint = "https://otlp.your-provider.com/v1/metrics"
+ otlp_headers = {
+ Authorization = "Bearer ${var.otlp_token}"
+ }
+}
+
+resource "openstatus_http_monitor" "api" {
+ name = "API Health Check"
+ url = "https://api.example.com/health"
+ periodicity = "1m"
+ active = true
+ regions = ["fly-iad", "fly-ams"]
+
+ open_telemetry {
+ endpoint = local.otlp_endpoint
+
+ dynamic "headers" {
+ for_each = local.otlp_headers
+ content {
+ key = headers.key
+ value = headers.value
+ }
+ }
+ }
+}
+```
-Use the openstatus CLI to apply the changes to your account.
+### 4. Apply the configuration
```bash
-openstatus monitors apply
+terraform plan # confirm only the open_telemetry block is changing
+terraform apply
```
-After applying the configuration, openstatus will send metrics to your specified endpoint after every check is completed.
+Once applied, openstatus sends metrics to your endpoint after every check completes.
-### 4. Verify in your observability platform
+### 5. Verify in your observability platform
Go to your observability platform and look for the new metrics coming from openstatus. You should be able to build dashboards and alerts based on this data.
diff --git a/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx b/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx
index b584ceae0..19213558d 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx
@@ -20,79 +20,81 @@ How can you confidently ensure your MCP server is healthy and responsive at all
## Solution
-openstatus monitors MCP servers by sending JSON-RPC `ping` requests to your endpoint from multiple global locations. This verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide walks you through setting up comprehensive monitoring for any MCP server using the openstatus CLI.
+openstatus monitors MCP servers by sending JSON-RPC `ping` requests to your endpoint from multiple global locations. This verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide declares those monitors with the openstatus Terraform provider, so your monitoring lives in version control alongside the rest of your infrastructure.
## Prerequisites
- An [openstatus account](https://app.openstatus.dev/login).
-- The [openstatus CLI installed](/docs/tutorial/get-started-with-openstatus-cli).
+- Terraform and the [openstatus provider](/docs/reference/terraform) configured — see [Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform) if you have not set it up yet.
- An MCP server with a publicly accessible endpoint.
- A basic understanding of the [JSON-RPC 2.0 protocol](https://www.jsonrpc.org/specification).
## Step-by-step guide
-### 1. Create your `openstatus.yaml` file
-
-openstatus allows you to define and manage your monitors using a YAML configuration file, which is ideal for GitOps workflows. This approach ensures your monitoring setup is version-controlled, auditable, and easily deployable.
-
-Create a file named `openstatus.yaml` and add the following configuration, adapting it for your own MCP endpoint. This example targets a Hugging Face MCP server.
-
-```yaml
-# yaml-language-server: $schema=https://www.openstatus.dev/schema.json
-
-mcp-server:
- name: "HF MCP Server"
- description: "Hugging Face MCP server monitoring"
- frequency: "1m"
- active: true
- regions: ["iad", "ams", "lax"]
- retry: 3
- kind: http
- request:
- url: https://hf.co/mcp
- method: POST
- body: >
- {
- "jsonrpc": "2.0",
- "id": "openstatus",
- "method": "ping"
- }
- headers:
- User-Agent: openstatus
- Accept: application/json, text/event-stream
- Content-Type: application/json
- assertions:
- - kind: statusCode
- compare: eq
- target: 200
- - kind: textBody
- compare: eq
- target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'
+### 1. Declare the monitor
+
+Add an `openstatus_http_monitor` resource, adapting it for your own MCP endpoint. This example
+targets a Hugging Face MCP server.
+
+```terraform
+resource "openstatus_http_monitor" "mcp_server" {
+ name = "HF MCP Server"
+ description = "Hugging Face MCP server monitoring"
+ url = "https://hf.co/mcp"
+ method = "POST"
+ periodicity = "1m"
+ active = true
+ retry = 3
+ regions = ["fly-iad", "fly-ams", "fly-lax"]
+
+ body = jsonencode({
+ jsonrpc = "2.0"
+ id = "openstatus"
+ method = "ping"
+ })
+
+ headers {
+ key = "Content-Type"
+ value = "application/json"
+ }
+
+ headers {
+ key = "Accept"
+ value = "application/json, text/event-stream"
+ }
+
+ status_code_assertions {
+ target = 200
+ comparator = "eq"
+ }
+
+ body_assertions {
+ target = "{\"result\":{},\"jsonrpc\":\"2.0\",\"id\":\"openstatus\"}"
+ comparator = "eq"
+ }
+}
```
### 2. Understand the configuration
-The key fields in this YAML configuration:
+The fields that matter for an MCP check:
- `name` and `description` — human-readable name and explanation for your monitor.
-- `frequency` — how often openstatus runs the check (e.g., `1m`, `5m`, `10m`).
-- `regions` — an array of geographic regions from which to perform checks (e.g., `["iad", "ams", "lax"]`). Monitoring from multiple regions helps detect localised issues.
-- `retry` — the number of times to retry a failed check before marking it as down.
-- `kind` — must be `http` for MCP servers.
-- `request`:
- - `url` — the full URL of your MCP server's JSON-RPC endpoint.
- - `method` — must be `POST` for JSON-RPC requests.
- - `body` — the JSON-RPC `ping` request payload.
- - `headers` — standard HTTP headers for JSON-RPC communication.
-- `assertions` — rules to validate the server's response.
- - `statusCode` — ensures the HTTP response is `200 OK`.
- - `textBody` — verifies that the response payload exactly matches the expected JSON-RPC `ping` result.
+- `url` — the full URL of your MCP server's JSON-RPC endpoint.
+- `method` — must be `POST` for JSON-RPC requests.
+- `periodicity` — how often openstatus runs the check (`30s`, `1m`, `5m`, `10m`, `30m`, `1h`).
+- `regions` — the locations the check runs from. Monitoring from several catches localised issues. Terraform uses the prefixed region codes (`fly-iad`), unlike the dashboard — see the [location reference](/docs/reference/location).
+- `retry` — how many times a failed check is retried before the monitor is marked down.
+- `body` — the JSON-RPC `ping` payload. `jsonencode` keeps it readable and correctly escaped.
+- `headers` — one block per header. openstatus already sends `User-Agent: OpenStatus/1.0`; override it only if your server cares.
+- `status_code_assertions` — ensures the HTTP response is `200 OK`.
+- `body_assertions` — verifies the response payload matches the expected JSON-RPC `ping` result.
### 3. Test your MCP server online first
Before deploying a monitor, confirm the server actually speaks MCP. The quickest way is the [MCP server health check](/play/mcp-health) — paste your URL and it runs the full handshake (`initialize`, `ping`, `tools/list`) from the browser, shows the per-step latency, and tells you whether the endpoint is Healthy, Partial, Auth Required, or Unreachable. Use it to read off the exact response your assertion needs to match.
-You can also test the `ping` endpoint manually with `curl`. This helps verify the `target` value for your `textBody` assertion.
+You can also test the `ping` endpoint manually with `curl`. This helps verify the `target` value for your body assertion.
```bash
curl -X POST \\
@@ -105,13 +107,14 @@ A healthy server should return a JSON response like `{"result":{},"jsonrpc":"2.0
### 4. Deploy your monitor
-Once your `openstatus.yaml` file is ready, use the openstatus CLI to create the monitor:
+Review the plan, then apply it:
```bash
-openstatus monitors apply --config openstatus.yaml
+terraform plan # confirm the monitor is what you expect
+terraform apply
```
-This command uploads your configuration, and monitoring will begin immediately.
+Monitoring begins as soon as the apply completes.
## Monitoring an MCP server that requires authentication
@@ -119,21 +122,26 @@ Most production MCP servers are not public. An unauthenticated `ping` against on
Add the same `Authorization` header your AI clients use:
-```yaml
- request:
- url: https://mcp.example.com/mcp
- method: POST
- headers:
- Authorization: Bearer <your-token>
- User-Agent: openstatus
- Accept: application/json, text/event-stream
- Content-Type: application/json
+```terraform
+variable "mcp_token" {
+ type = string
+ sensitive = true
+}
+
+resource "openstatus_http_monitor" "mcp_server" {
+ # ...
+
+ headers {
+ key = "Authorization"
+ value = "Bearer ${var.mcp_token}"
+ }
+}
```
Two things to plan for:
-- **Token rotation is the most common false alarm.** When the token expires, the monitor goes down while the server is perfectly healthy. Assert on `statusCode` `eq` `200` so a `401` fails loudly and is easy to recognise, rather than debugging it as an outage.
-- **Keep the credential out of your repository.** This YAML is meant to be version-controlled, so use a token scoped to read-only health checks — not a production credential — and rotate it on a schedule you control.
+- **Token rotation is the most common false alarm.** When the token expires, the monitor goes down while the server is perfectly healthy. Assert on the status code being `200` so a `401` fails loudly and is easy to recognise, rather than debugging it as an outage.
+- **Keep the credential out of your repository.** Mark the variable `sensitive` and pass it in with `TF_VAR_mcp_token` or from a secrets manager. Use a token scoped to read-only health checks — not a production credential — and rotate it on a schedule you control.
If you are unsure which authorization server issues your token, the [health check tool](/play/mcp-health) parses the `WWW-Authenticate` challenge and surfaces the OAuth resource metadata for you.
@@ -143,35 +151,43 @@ A `ping` proves the server is answering. It does not prove the server still expo
Add a second monitor that calls `tools/list` and asserts a known tool name is present:
-```yaml
-mcp-tools:
- name: "MCP tools/list"
- description: "Verify the MCP server still exposes its tools"
- frequency: "5m"
- active: true
- regions: ["iad", "ams", "sin"]
- retry: 3
- kind: http
- request:
- url: https://hf.co/mcp
- method: POST
- body: >
- {
- "jsonrpc": "2.0",
- "id": "openstatus",
- "method": "tools/list"
- }
- headers:
- User-Agent: openstatus
- Accept: application/json, text/event-stream
- Content-Type: application/json
- assertions:
- - kind: statusCode
- compare: eq
- target: 200
- - kind: textBody
- compare: contains
- target: "your_tool_name"
+```terraform
+resource "openstatus_http_monitor" "mcp_tools" {
+ name = "MCP tools/list"
+ description = "Verify the MCP server still exposes its tools"
+ url = "https://hf.co/mcp"
+ method = "POST"
+ periodicity = "5m"
+ active = true
+ retry = 3
+ regions = ["fly-iad", "fly-ams", "fly-sin"]
+
+ body = jsonencode({
+ jsonrpc = "2.0"
+ id = "openstatus"
+ method = "tools/list"
+ })
+
+ headers {
+ key = "Content-Type"
+ value = "application/json"
+ }
+
+ headers {
+ key = "Accept"
+ value = "application/json, text/event-stream"
+ }
+
+ status_code_assertions {
+ target = 200
+ comparator = "eq"
+ }
+
+ body_assertions {
+ target = "your_tool_name"
+ comparator = "contains"
+ }
+}
```
Assert on the bare tool name, not on `"name":"your_tool_name"`. `contains` matches literally, and servers differ in whether they emit a space after the JSON key — an assertion written against the compact form fails the moment a server pretty-prints its response.
@@ -183,7 +199,7 @@ Assert on the bare tool name, not on `"name":"your_tool_name"`. `contains` match
Not every MCP failure deserves the same response:
- **`ping` failing across all regions** — the server is down. Alert immediately.
-- **`ping` failing in one region** — usually a network path problem rather than your server. Retries handle most of these, which is what `retry: 3` is for.
+- **`ping` failing in one region** — usually a network path problem rather than your server. Retries handle most of these, which is what `retry = 3` is for.
- **`401` after a period of `200`s** — a rotated or expired token. This is a credentials problem, not an outage.
- **`tools/list` succeeding but missing a tool** — a deploy removed or renamed a tool. Nothing is "down", but your agents are already broken.
- **Latency climbing on `tools/list` while `ping` stays flat** — the server is under load in its application layer rather than its network layer.
@@ -195,7 +211,7 @@ Not every MCP failure deserves the same response:
- Handled authenticated endpoints without turning token rotation into a false outage
- Added a `tools/list` check so a missing tool is caught before your agents hit it
- Set up global monitoring to detect localised or widespread issues
-- Automated monitor deployment using a version-controlled YAML configuration
+- Declared both monitors in Terraform, so they are reviewable and reproducible
Both monitors run on [openstatus uptime monitoring](/uptime-monitoring) from up to 28 regions, with alerting and history — so a broken handshake reaches you before it reaches the agents depending on it.
@@ -209,4 +225,4 @@ Both monitors run on [openstatus uptime monitoring](/uptime-monitoring) from up
- **[JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification)** — deep dive into the JSON-RPC protocol.
- **[MCP official documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring)** — official insights into MCP health checks.
- **[HTTP monitor reference](/docs/reference/http-monitor)** — comprehensive reference for HTTP monitors.
-- **[CLI reference](/docs/reference/cli-reference)** — full documentation for the openstatus CLI.
+- **[Terraform provider reference](/docs/reference/terraform)** — every resource, argument, and block.
diff --git a/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx b/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx
index 1782c792c..65e2681cd 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx
@@ -89,7 +89,9 @@ async function CustomStatusWidget() {
### Pointing at a self-hosted API
Both `getStatus` and `StatusWidget` call `https://api.openstatus.dev` by default. If you self-host
-openstatus, set `OPENSTATUS_API_URL` on the server, or pass the base URL as the second argument:
+openstatus, set `OPENSTATUS_API_URL` on the server — that is the only lever for `StatusWidget`,
+which takes just `slug` and `href`. `getStatus` additionally accepts the base URL as a second
+argument:
```tsx
const res = await getStatus("slug", "https://api.status.example.com");
diff --git a/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx b/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx
index 6b206cebc..90ecd8f12 100644
--- a/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx
+++ b/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx
@@ -125,11 +125,18 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui
5. **Set workspace limits**
- Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database. The following command updates the limits for the workspace with `id = 1`:
+ Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database.
+
+ Every key you leave out falls back to its **free-plan default**, not to "unlimited" — a
+ partial payload silently caps the workspace at 3 page components, 6 regions, and no OTLP export,
+ screenshots, response logs, custom theme, or translations. The block below sets every key the
+ current `limitsSchema` (`packages/db/src/schema/plan/schema.ts`) defines, so nothing falls
+ through. Change the `WHERE id = 1` at the end if your workspace has a different ID.
```bash
- curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
- -d '{"statements":["UPDATE workspace SET limits = '\''{\\"monitors\\":100,\\"periodicity\\":[\\"30s\\",\\"1m\\",\\"5m\\",\\"10m\\",\\"30m\\",\\"1h\\"],\\"multi-region\\":true,\\"data-retention\\":\\"24 months\\",\\"status-pages\\":20,\\"maintenance\\":true,\\"status-subscribers\\":true,\\"custom-domain\\":true,\\"password-protection\\":true,\\"white-label\\":true,\\"notifications\\":true,\\"sms\\":true,\\"pagerduty\\":true,\\"notification-channels\\":50,\\"members\\":\\"Unlimited\\",\\"audit-log\\":true,\\"private-locations\\":true}'\'' WHERE id = 1"]}'
+ curl -sS -X POST http://localhost:8080/ -H "Content-Type: application/json" -d @- <<'JSON'
+ {"statements":["UPDATE workspace SET limits = '{\"monitors\":100,\"synthetic-checks\":100000,\"periodicity\":[\"30s\",\"1m\",\"5m\",\"10m\",\"30m\",\"1h\"],\"multi-region\":true,\"max-regions\":28,\"data-retention\":\"24 months\",\"regions\":[\"ams\",\"arn\",\"bom\",\"cdg\",\"dfw\",\"ewr\",\"fra\",\"gru\",\"iad\",\"jnb\",\"lax\",\"lhr\",\"nrt\",\"ord\",\"sjc\",\"sin\",\"syd\",\"yyz\",\"koyeb_fra\",\"koyeb_was\",\"koyeb_sin\",\"koyeb_tyo\",\"koyeb_par\",\"koyeb_sfo\",\"railway_europe-west4-drams3a\",\"railway_us-east4-eqdc4a\",\"railway_asia-southeast1-eqsg3a\",\"railway_us-west2\"],\"private-locations\":true,\"screenshots\":true,\"response-logs\":true,\"otel\":true,\"status-pages\":20,\"page-components\":500,\"maintenance\":true,\"monitor-values-visibility\":true,\"uptime-history\":true,\"status-subscribers\":true,\"custom-domain\":true,\"i18n\":true,\"password-protection\":true,\"email-domain-protection\":true,\"ip-restriction\":true,\"white-label\":true,\"no-index\":true,\"custom-theme\":true,\"notifications\":true,\"pagerduty\":true,\"opsgenie\":true,\"grafana-oncall\":true,\"whatsapp\":true,\"sms\":true,\"sms-limit\":1000,\"notification-channels\":50,\"members\":\"Unlimited\",\"audit-log\":true,\"sso\":true,\"slack-agent\":true}' WHERE id = 1"]}
+ JSON
```
You can find your workspace ID by querying the database:
diff --git a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
index da7f9e562..bef43ba75 100644
--- a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
+++ b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
@@ -205,10 +205,16 @@ Now that the services are running, you can access the dashboard and perform the
- Sign up and create a new workspace.
- Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database.
- The following command updates the limits for the workspace with `id = 1`. If your workspace has a different ID, change the `WHERE id = 1` part of the command.
+ Every key you leave out falls back to its **free-plan default**, not to "unlimited" — a
+ partial payload silently caps the workspace at 3 page components, 6 regions, and no OTLP export,
+ screenshots, response logs, custom theme, or translations. The block below sets every key the
+ current `limitsSchema` (`packages/db/src/schema/plan/schema.ts`) defines, so nothing falls
+ through. Change the `WHERE id = 1` at the end if your workspace has a different ID.
+
```bash
- curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
- -d '{"statements":["UPDATE workspace SET limits = '\''{\\"monitors\\":100,\\"periodicity\\":[\\"30s\\",\\"1m\\",\\"5m\\",\\"10m\\",\\"30m\\",\\"1h\\"],\\"multi-region\\":true,\\"data-retention\\":\\"24 months\\",\\"status-pages\\":20,\\"maintenance\\":true,\\"status-subscribers\\":true,\\"custom-domain\\":true,\\"password-protection\\":true,\\"white-label\\":true,\\"notifications\\":true,\\"sms\\":true,\\"pagerduty\\":true,\\"notification-channels\\":50,\\"members\\":\\"Unlimited\\",\\"audit-log\\":true,\\"private-locations\\":true}'\'' WHERE id = 1"]}'
+ curl -sS -X POST http://localhost:8080/ -H "Content-Type: application/json" -d @- <<'JSON'
+ {"statements":["UPDATE workspace SET limits = '{\"monitors\":100,\"synthetic-checks\":100000,\"periodicity\":[\"30s\",\"1m\",\"5m\",\"10m\",\"30m\",\"1h\"],\"multi-region\":true,\"max-regions\":28,\"data-retention\":\"24 months\",\"regions\":[\"ams\",\"arn\",\"bom\",\"cdg\",\"dfw\",\"ewr\",\"fra\",\"gru\",\"iad\",\"jnb\",\"lax\",\"lhr\",\"nrt\",\"ord\",\"sjc\",\"sin\",\"syd\",\"yyz\",\"koyeb_fra\",\"koyeb_was\",\"koyeb_sin\",\"koyeb_tyo\",\"koyeb_par\",\"koyeb_sfo\",\"railway_europe-west4-drams3a\",\"railway_us-east4-eqdc4a\",\"railway_asia-southeast1-eqsg3a\",\"railway_us-west2\"],\"private-locations\":true,\"screenshots\":true,\"response-logs\":true,\"otel\":true,\"status-pages\":20,\"page-components\":500,\"maintenance\":true,\"monitor-values-visibility\":true,\"uptime-history\":true,\"status-subscribers\":true,\"custom-domain\":true,\"i18n\":true,\"password-protection\":true,\"email-domain-protection\":true,\"ip-restriction\":true,\"white-label\":true,\"no-index\":true,\"custom-theme\":true,\"notifications\":true,\"pagerduty\":true,\"opsgenie\":true,\"grafana-oncall\":true,\"whatsapp\":true,\"sms\":true,\"sms-limit\":1000,\"notification-channels\":50,\"members\":\"Unlimited\",\"audit-log\":true,\"sso\":true,\"slack-agent\":true}' WHERE id = 1"]}
+ JSON
```
You can find your workspace ID by inspecting the database with a command like `curl -X POST http://localhost:8080/ -H "Content-Type: application/json" -d '{"statements":["SELECT id, name FROM workspace"]}'`.
@@ -239,7 +245,7 @@ Now that the services are running, you can access the dashboard and perform the
The two environment variables are:
- - `OPENSTATUS_KEY` — the key you copied from the dashboard. Some older docs call this `OPENSTATUS_TOKEN`; that name is not read by the probe.
+ - `OPENSTATUS_KEY` — the key you copied from the dashboard. Some older docs call this `OPENSTATUS_TOKEN`; that name is not read by the probe, which exits on startup with `OPENSTATUS_KEY is required` if the variable is unset.
- `OPENSTATUS_INGEST_URL` — the URL of your **ingest server**, i.e. the `private-location` service on port **8081**. If you don't set it, the probe defaults to openstatus Cloud (`https://openstatus-private-location.fly.dev`) and your self-hosted instance will never see a check.
If you run the probe on the same Docker network as the rest of the stack, use the internal address instead — `http://private-location:8080`.
diff --git a/apps/web/src/content/pages/docs/reference/http-monitor.mdx b/apps/web/src/content/pages/docs/reference/http-monitor.mdx
index 86e0b0387..98f1639bf 100644
--- a/apps/web/src/content/pages/docs/reference/http-monitor.mdx
+++ b/apps/web/src/content/pages/docs/reference/http-monitor.mdx
@@ -191,10 +191,16 @@ compared as a string, using the same comparators as body assertions.
A body that fails to parse as JSON fails the assertion.
-<Aside>
-JSON body assertions are available through the REST and ConnectRPC APIs, the CLI, and Terraform.
-The dashboard's assertion editor currently offers status, header, and (text) body assertions
-only — a monitor created with a JSON body assertion keeps it, but you cannot add one from the UI.
+<Aside type="caution">
+JSON body assertions cannot currently be created from any surface. The checker evaluates them,
+and a monitor that already stores one keeps working, but none of the write paths accept one:
+the dashboard's assertion editor offers status, header, and (text) body assertions only; the v1
+REST API leaves the JSON body variant out of its assertion union; and the ConnectRPC API,
+the SDKs, and the Terraform provider have no equivalent message.
+
+One consequence is worth knowing if you hold an existing JSON body assertion: reading such a
+monitor back over ConnectRPC reports it as a plain body assertion, with the JSONPath dropped.
+The stored assertion itself is unchanged and the checker still evaluates the path.
</Aside>
#### Status code assertions
diff --git a/apps/web/src/content/pages/docs/reference/incident.mdx b/apps/web/src/content/pages/docs/reference/incident.mdx
index 82ba2e3c6..45c261741 100644
--- a/apps/web/src/content/pages/docs/reference/incident.mdx
+++ b/apps/web/src/content/pages/docs/reference/incident.mdx
@@ -28,7 +28,12 @@ An incident's lifecycle is tracked with timestamps rather than a manual workflow
- **Open** — created when the failure threshold is met. `resolvedAt` is null.
- **Acknowledged** — a team member has taken ownership. `acknowledgedAt` and `acknowledgedBy` are set.
-- **Resolved** — either auto-resolved when the monitor recovers (`autoResolved: true`) or manually resolved, setting `resolvedAt` and `resolvedBy`.
+- **Resolved** — either auto-resolved (`autoResolved: true`) or manually resolved, setting `resolvedAt` and `resolvedBy`.
+
+Auto-resolution fires when the monitor leaves the `error` state by the same region-agreement rule
+that opened the incident. That includes a transition to `degraded`, not only to `active`: a monitor
+that improves from down to slow closes its open incident. The notification that goes out matches the
+new state — a recovery alert for `active`, a degraded alert for `degraded`.
The stored `status` field accepts `triage` (the default), `investigating`, `identified`, `monitoring`, `resolved`, and `duplicated`.
diff --git a/apps/web/src/content/pages/docs/reference/location.mdx b/apps/web/src/content/pages/docs/reference/location.mdx
index 34c2edb2f..5d46ec612 100644
--- a/apps/web/src/content/pages/docs/reference/location.mdx
+++ b/apps/web/src/content/pages/docs/reference/location.mdx
@@ -12,15 +12,22 @@ You can use these locations to:
- Allowlist monitoring IPs in your firewall.
- Understand where requests originate during synthetic monitoring.
-## Two forms of the same region code
+## Three forms of the same region code
-The dashboard, the CLI, and the deprecated v1 REST API use the **bare** code (`iad`, `fra`,
-`koyeb_fra`, `railway_us-east4-eqdc4a`). The ConnectRPC API, the Terraform provider, and the SDKs
-use a **prefixed, hyphenated** form derived from the `Region` enum (`fly-iad`, `fly-fra`,
-`koyeb-fra`, `railway-us-east4`).
+The same probe is addressed by a different spelling depending on the surface you are using:
-They address the same probe — pick whichever form the surface you are using expects. The tables
-below list both.
+| Surface | Form | Example |
+|---|---|---|
+| Dashboard, CLI, deprecated v1 REST API | **bare** code | `iad`, `fra`, `koyeb_fra`, `railway_us-east4-eqdc4a` |
+| Terraform provider | **prefixed, hyphenated** | `fly-iad`, `fly-fra`, `koyeb-fra`, `railway-us-east4` |
+| ConnectRPC API and the SDKs | the **protobuf enum** value | `REGION_FLY_IAD`, `REGION_FLY_FRA`, `REGION_KOYEB_FRA`, `REGION_RAILWAY_US_EAST4` |
+
+The SDKs expose the enum as a generated constant rather than a raw string — `Region.FLY_IAD` in
+the Node.js SDK, `Region::REGION_FLY_IAD` in PHP — so you rarely type the value out.
+
+Pick whichever form the surface you are using expects. The tables below list the bare and
+prefixed codes; the enum value is the prefixed code upper-cased with `-` replaced by `_` and
+`REGION_` prepended.
### Fly.io regions and monitoring IPs
diff --git a/apps/web/src/content/pages/docs/reference/mcp-server.mdx b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
index 4ab766b3e..8001ad337 100644
--- a/apps/web/src/content/pages/docs/reference/mcp-server.mdx
+++ b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
@@ -47,7 +47,7 @@ Send an openstatus API key in the `x-openstatus-key` header. This is the same ke
x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
-Get a key from the dashboard's **Settings > API Tokens**. When both credentials are present, the header wins.
+Get a key from the dashboard's **Settings > General**, in the **API Keys** card. When both credentials are present, the header wins.
### Scopes
@@ -122,6 +122,21 @@ Registered only when the workspace plan includes the `audit-log` feature — oth
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.
+### Resources
+
+Alongside its tools, the server exposes a small set of read-only MCP **resources** — public
+documents carrying no workspace data, so they are available on any credential and any scope.
+List them with `resources/list` and fetch one with `resources/read`:
+
+| Resource | URI | Contents |
+|---|---|---|
+| `openapi-specification` | `https://api.openstatus.dev/openapi.json` | The full OpenAPI document, served from the binary rather than fetched. |
+| `mcp-server-reference` | `https://www.openstatus.dev/docs/reference/mcp-server` | This page. |
+| `site-index` | `https://www.openstatus.dev/llms.txt` | `llms.txt`: product context, pricing, and a linked index of every page on openstatus.dev. |
+
+Remotely fetched resources are capped at a 5-second timeout and never resolve empty: on a failure
+the read returns a short pointer back to the same URI rather than a blank body.
+
### Notifying subscribers
Every publishing tool — `create_status_report`, `add_status_report_update`, `resolve_status_report`, `create_maintenance` — has a **required** `notify: boolean` field, with 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. `update_status_report` edits metadata only and carries no `notify` field at all.
diff --git a/apps/web/src/content/pages/docs/reference/private-location.mdx b/apps/web/src/content/pages/docs/reference/private-location.mdx
index 6249d362c..1d0071fe5 100644
--- a/apps/web/src/content/pages/docs/reference/private-location.mdx
+++ b/apps/web/src/content/pages/docs/reference/private-location.mdx
@@ -38,7 +38,9 @@ Private locations require the **Pro** or **Scale** plan.
## API surface
-Private locations can be created, listed, updated, and deleted from:
+Private locations can be created, listed, updated, and deleted from the dashboard, the
+ConnectRPC API, the Terraform provider, and the Node.js SDK. The CLI covers reads and creation
+only, and the MCP server is read-only.
- the **dashboard** (Settings → Private Locations);
- the **ConnectRPC API** — `PrivateLocationService` exposes `CreatePrivateLocation`, `GetPrivateLocation`, `ListPrivateLocations`, `UpdatePrivateLocation`, and `DeletePrivateLocation` (see the [API reference](https://api.openstatus.dev/openapi));
diff --git a/apps/web/src/content/pages/docs/reference/status-page.mdx b/apps/web/src/content/pages/docs/reference/status-page.mdx
index 5d2440380..90ed5034c 100644
--- a/apps/web/src/content/pages/docs/reference/status-page.mdx
+++ b/apps/web/src/content/pages/docs/reference/status-page.mdx
@@ -193,20 +193,29 @@ Two optional URLs shown in the status page header.
When enabled the page is indexable. Disable it to serve a `noindex` directive and keep the page
out of search results — useful for an internal or pre-launch page. Available on paid plans.
-### JSON feed
+### Feeds
-**Type:** Read-only endpoint
-**Format:** JSON
+**Type:** Read-only endpoints
-Provides a machine-readable JSON representation of your status page data. This feed can be accessed by appending `/feed/json` to your status page URL.
+Every status page publishes its events in three machine-readable formats, reached by appending a
+path to the page URL:
+
+| Path | Format | Contents |
+|---|---|---|
+| `/feed/json` | JSON | Full page state: components, status reports, maintenances, and the deprecated monitor fields below. |
+| `/feed/rss` | RSS 2.0 | Status reports and maintenances as feed entries, for readers and automations. |
+| `/feed/atom` | Atom 1.0 | The same entries in Atom. |
**Example:** `https://status.openstatus.dev/feed/json`
+On a password-protected page the feeds are protected too; append `?pw=your-secret-password` to
+read them from a feed reader.
+
**Deprecation notice:**
The following fields are deprecated and will be removed in a future version:
-- **`monitors`** (top-level) — use `pageComponents` instead, which provides a more flexible component-based structure that supports both monitors and external services.
+- **`monitors`** (top-level) — use `pageComponents` instead, which provides a more flexible component-based structure that supports both monitor-linked and static components.
- **`maintenances[].monitors`** — use `maintenances[].pageComponents` instead, which references page component IDs rather than monitor IDs.
- **`statusReports[].monitors`** — use `statusReports[].pageComponents` instead, which references page component IDs rather than monitor IDs.
diff --git a/apps/web/src/content/pages/docs/tutorial/create-your-first-status-page.mdx b/apps/web/src/content/pages/docs/tutorial/create-your-first-status-page.mdx
index 8f07b9095..d755bd153 100644
--- a/apps/web/src/content/pages/docs/tutorial/create-your-first-status-page.mdx
+++ b/apps/web/src/content/pages/docs/tutorial/create-your-first-status-page.mdx
@@ -15,7 +15,7 @@ description: "A step-by-step tutorial to create and publish your first status pa
In this tutorial, you'll create a public status page to communicate your service's health to users. A status page is a transparent way to show real-time uptime information and keep your users informed during incidents.
-By the end you'll have a public status page showing your service health, monitors displayed on the page, and a working understanding of the privacy and security options.
+By the end you'll have a public status page with a component for each service you want to show, and a working understanding of where custom domains and access control are configured.
<Aside type="tip">
Coming from another provider? openstatus can import components, incidents, maintenances, and subscribers from your existing setup. See the migration guides for [Atlassian Statuspage](/guides/migrate-from-atlassian-statuspage), [Better Stack](/guides/migrate-from-betterstack), [Instatus](/guides/migrate-from-instatus), or [Checkly](/guides/migrate-from-checkly) instead of building from scratch.
@@ -33,48 +33,63 @@ Navigate to the **Status Pages** page from the sidebar and click the **Create St
/>
-### 2. Configure the status page
+### 2. Name the page
-Fill in the basic details for your status page:
+The create form asks for four things, and only the first two are required:
-- **Title:** A name for your status page (e.g., "Acme Status" or "API Health")
-- **Slug:** The URL path for your status page (e.g., `acme` creates `acme.openstatus.dev`)
+- **Title** — a name for your status page (e.g. "Acme Status" or "API Health").
+- **Slug** — the subdomain your page is served from (e.g. `acme` creates `acme.openstatus.dev`).
+- **Icon** — an optional favicon shown in the browser tab.
+- **Description** — an optional line shown under the title on the public page.
-<Image
- src="/docs/tutorial/create-status-page/create-status-page-2.png"
- alt="Status page configuration form showing title, slug, and monitor selection"
-/>
+Submit, and you land on the page's **Settings** tab. Everything else — components, custom
+domain, access control, theme, locales — is configured from here on the page's own tabs.
+
+### 3. Add components
-#### Add monitors
+Open the **Components** tab and add a component for each service you want to show. A component
+is what your visitors see, and it comes in two kinds:
-Select the monitors you want to display on your status page. Each monitor will show as a separate service with its own uptime bar. You can add multiple monitors to give users a complete picture of your infrastructure health.
+- **Monitor components** are linked to one of your monitors and track its status automatically.
+- **Static components** have no monitor behind them; you drive their status with status reports
+ and maintenance windows. Use these for third-party dependencies.
-#### Custom domain
+Give the component a name your users will recognise — it does not have to match the monitor's
+internal name. See the [page components reference](/docs/reference/page-components) for groups,
+ordering, and how each event type affects a component's status.
-You can use your own domain (e.g., `status.yourdomain.com`) instead of the default `*.openstatus.dev` subdomain. To set this up:
+**Checkpoint:** open your status page (the link is at the top of the page's settings). You
+should see each component listed with its uptime bar.
-1. Enter your custom domain in the **Custom Domain** field
-2. Configure DNS records based on your domain type:
- - **Subdomain** (e.g., `status.yourdomain.com`): Add a CNAME record pointing to `cname.vercel-dns.com`
- - **Apex domain** (e.g., `yourdomain.com`): Add an A record pointing to `76.76.21.21`
-3. Wait for DNS propagation (usually a few minutes, up to 48 hours)
-4. If your domain is already registered on another Vercel project, you may need to add a **TXT record** to verify ownership. The dashboard will show the exact TXT values if this step is required.
+### 4. Optional: custom domain
-The dashboard will show you the exact DNS records to configure after you save your custom domain.
+On the **Settings** tab, the **Custom Domain** card lets you serve the page from your own
+domain (e.g. `status.yourdomain.com`) instead of the `*.openstatus.dev` subdomain:
-See the [status page reference](/docs/reference/status-page) for detailed DNS configuration instructions.
+1. Enter your domain and submit.
+2. Configure DNS based on your domain type:
+ - **Subdomain** (e.g. `status.yourdomain.com`): add a CNAME record pointing to `cname.vercel-dns.com`.
+ - **Apex domain** (e.g. `yourdomain.com`): add an A record pointing to `76.76.21.21`.
+3. Wait for DNS propagation (usually a few minutes, up to 48 hours).
+4. If the domain is already registered on another Vercel project, you also need a **TXT record**
+ to prove ownership. The dashboard shows the exact values when this step applies.
-#### Password protection
+The dashboard displays the exact records to configure after you save the domain. See the
+[status page reference](/docs/reference/status-page) for the full DNS table.
-Enable password protection to restrict access to your status page. This is useful for internal status pages that should only be visible to your team or specific customers. Enter a password, and visitors will be prompted to authenticate before viewing the page.
+### 5. Optional: restrict access
-**Checkpoint:** After saving, click the link to your status page (shown at the top of the settings). You should see your monitors listed with uptime bars.
+Also on the **Settings** tab, the **Page Access** card controls who can see the page. Password
+protection is the simplest option — set a password and visitors are prompted before the page
+loads, which is what you want for an internal page. Magic-link and IP-range restriction are
+available as paid add-ons; the [status page reference](/docs/reference/status-page) covers all
+four access types.
## What you've accomplished
- Created your first status page
-- Added monitors to display service health
-- Learned about custom domains and password protection
+- Added components so visitors can see service health
+- Learned where custom domains and access control live
## What's next
diff --git a/apps/web/src/content/pages/docs/tutorial/get-started-with-openstatus-cli.mdx b/apps/web/src/content/pages/docs/tutorial/get-started-with-openstatus-cli.mdx
index 2b88602f9..217c172c7 100644
--- a/apps/web/src/content/pages/docs/tutorial/get-started-with-openstatus-cli.mdx
+++ b/apps/web/src/content/pages/docs/tutorial/get-started-with-openstatus-cli.mdx
@@ -1,7 +1,7 @@
---
category: Tutorials
title: Get Started with openstatus CLI
-description: "Step-by-step tutorial to install and use the openstatus CLI for monitoring as code"
+description: "Step-by-step tutorial to install the openstatus CLI and export your workspace to Terraform"
---
@@ -11,9 +11,9 @@ description: "Step-by-step tutorial to install and use the openstatus CLI for mo
| **Level** | Intermediate |
| **Prerequisites** | openstatus account, command-line experience, API key from your workspace (Settings > General > API Keys) |
-In this tutorial, you'll use the openstatus CLI to manage your monitors as code. This lets you version-control your monitoring configuration, automate deployments, and implement GitOps workflows.
+In this tutorial, you'll install the openstatus CLI and use it to export your existing workspace into Terraform configuration. That gives you a version-controlled, reviewable definition of your monitoring you can then manage with the standard `plan` / `apply` workflow.
-By the end you'll have the openstatus CLI installed on your system, your monitors exported to a YAML configuration file, and a working sense of the monitoring-as-code workflow.
+By the end you'll have the openstatus CLI installed and authenticated, and your monitors, status pages, and notification channels written out as `.tf` files.
<Image
src="/docs/tutorial/get-started-with-openstatus-cli/CLI.png"
@@ -82,39 +82,46 @@ $env:OPENSTATUS_API_TOKEN="<your-api-token>"
<Aside type="note">The CLI reads `OPENSTATUS_API_TOKEN`. The openstatus SDKs (Node.js, Python, PHP) read the same API key value from `OPENSTATUS_API_KEY` instead — you can set both to the same value if you use both tools.</Aside>
-## Import existing monitors
+## Export your workspace to Terraform
-Start by importing your existing monitors from your workspace to a YAML file:
+The CLI can write your existing workspace out as ready-to-use Terraform configuration, so you
+don't have to translate your monitors by hand:
```bash
-openstatus monitors import
+openstatus terraform generate
```
-You should see output confirming the import:
+Files are written to `./openstatus-terraform/` by default; pass `--output-dir` to choose another
+directory, and `--force` to overwrite an existing one. The export covers monitors, status pages,
+component groups, notification channels, and private locations.
-```
-Successfully imported X monitors to openstatus.yaml
-```
+**Checkpoint:** open the generated `.tf` files and confirm your monitors are there, with the names
+and URLs you expect.
-This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.
+## Manage it with Terraform
-**Checkpoint:** Open the `openstatus.yaml` file and verify it contains your monitors. You should see entries with your monitor names and URLs.
+From the output directory, the standard Terraform workflow takes over:
-## Manage monitors as code
+```bash
+terraform init # download the openstatus provider
+terraform plan # preview what will change
+terraform apply # apply the changes
+```
-Now you can add, remove, or update monitors in the YAML file and apply your changes:
+To adopt resources that already exist rather than recreate them, import them into state first:
```bash
-openstatus monitors apply
+terraform import openstatus_http_monitor.website <monitor_id>
```
-The CLI will show you a diff of changes before applying them, ensuring you're aware of what will be modified.
+From here on, edit the `.tf` files, open a pull request, and let `terraform plan` show the diff
+before anything reaches your workspace.
## What you've accomplished
- Installed the openstatus CLI
- Configured API authentication
-- Imported monitors to a YAML file
+- Exported your workspace to Terraform configuration
- Learned the monitoring-as-code workflow
## Troubleshooting
@@ -142,19 +149,20 @@ export PATH="$HOME/.local/bin:$PATH"
2. Regenerate the key in your workspace settings (Settings > General > API Keys)
3. Make sure there are no extra spaces or newlines in the token value
-### "no monitors found" on import
+### The export is empty
-**Cause:** Your workspace has no monitors, or the token belongs to a different workspace.
+**Cause:** Your workspace has no resources yet, or the token belongs to a different workspace.
-**Fix:** Create at least one monitor in the dashboard first, then retry the import.
+**Fix:** Confirm which workspace the token belongs to with `openstatus whoami`, create at least one
+monitor in the dashboard, then re-run the export.
## What's next
-- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — example of CLI-based monitor configuration.
-- **[Run synthetic tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — automate monitoring in your pipeline.
+- **[Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform)** — the end-to-end Terraform workflow.
+- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — a worked monitor definition.
### Learn more
- **[Monitoring-as-code concept](/docs/concept/uptime-monitoring-as-code)** — why manage monitors as code.
- **[CLI reference](/docs/reference/cli-reference)** — all available commands.
-- **[YAML configuration examples](https://github.com/openstatusHQ/cli-template)** — sample configurations.
+- **[Terraform provider reference](/docs/reference/terraform)** — every resource, argument, and block.
diff --git a/apps/web/src/content/pages/docs/tutorial/getting-started.mdx b/apps/web/src/content/pages/docs/tutorial/getting-started.mdx
index 3dd5d456b..ba7829cda 100644
--- a/apps/web/src/content/pages/docs/tutorial/getting-started.mdx
+++ b/apps/web/src/content/pages/docs/tutorial/getting-started.mdx
@@ -22,7 +22,7 @@ If you're new, follow the tutorials below in order. Each one builds on the previ
Once you're comfortable with the dashboard, manage your stack as code:
-- **[Get started with the openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli)** (~10 min) — install the CLI, authenticate, and import your monitors to a YAML file you can version-control.
+- **[Get started with the openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli)** (~10 min) — install the CLI, authenticate, and export your workspace to Terraform configuration you can version-control.
- **[Manage status reports from the CLI](/docs/tutorial/manage-status-reports-cli)** (~10 min) — open, update, and resolve a status report from the terminal during an incident.
## What's next
diff --git a/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx b/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx
index 57f372285..7dcd1fded 100644
--- a/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx
+++ b/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx
@@ -16,7 +16,7 @@ This tutorial uses **email** because it's the channel that needs the least setup
## 1. Create a notification channel
-Navigate to **Settings** > **Notification Channels** in the dashboard and click **Create Notification Channel**.
+Open **Notifications** in the dashboard sidebar and click **Create Notification Channel**.
Pick **Email** as the channel type and fill in two fields: