Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: experiment docs web (#2223)
Maximilian Kaskef9187e36f3ff
diff --git a/apps/web/public/docs/cli/CLI.png b/apps/web/public/docs/cli/CLI.pngnew file mode 100644index 000000000..20c6df035Binary files /dev/null and b/apps/web/public/docs/cli/CLI.png differdiff --git a/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-1.png b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-1.pngnew file mode 100644index 000000000..d75dee832Binary files /dev/null and b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-1.png differdiff --git a/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-2.png b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-2.pngnew file mode 100644index 000000000..6d3797630Binary files /dev/null and b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-2.png differdiff --git a/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-3.png b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-3.pngnew file mode 100644index 000000000..69fa14e48Binary files /dev/null and b/apps/web/public/docs/guides/how-deploy-checker-koyeb/koyeb-3.png differdiff --git a/apps/web/public/docs/guides/how-deploy-status-page-cf-pages/status-page.png b/apps/web/public/docs/guides/how-deploy-status-page-cf-pages/status-page.pngnew file mode 100644index 000000000..7e31f399dBinary files /dev/null and b/apps/web/public/docs/guides/how-deploy-status-page-cf-pages/status-page.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/cloudflare-log.png b/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/cloudflare-log.pngnew file mode 100644index 000000000..1bd069dd5Binary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/cloudflare-log.png differdiff --git a/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/private-location.jpg b/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/private-location.jpgnew file mode 100644index 000000000..21169afeaBinary files /dev/null and b/apps/web/public/docs/guides/how-to-deploy-probes-cf-containters/private-location.jpg differdiff --git a/apps/web/public/docs/guides/how-to-export-metrics-via-otel/grafana.png b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/grafana.pngnew file mode 100644index 000000000..8b98dbd11Binary files /dev/null and b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/grafana.png differdiff --git a/apps/web/public/docs/guides/how-to-export-metrics-via-otel/honeycomb.jpg b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/honeycomb.jpgnew file mode 100644index 000000000..ce0184809Binary files /dev/null and b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/honeycomb.jpg differdiff --git a/apps/web/public/docs/guides/how-to-export-metrics-via-otel/newrelic.jpg b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/newrelic.jpgnew file mode 100644index 000000000..7e2c0b011Binary files /dev/null and b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/newrelic.jpg differdiff --git a/apps/web/public/docs/guides/how-to-export-metrics-via-otel/signoz.jpg b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/signoz.jpgnew file mode 100644index 000000000..5037fcc99Binary files /dev/null and b/apps/web/public/docs/guides/how-to-export-metrics-via-otel/signoz.jpg differdiff --git a/apps/web/public/docs/guides/latency-ci-integration-test/github-api-token.png b/apps/web/public/docs/guides/latency-ci-integration-test/github-api-token.pngnew file mode 100644index 000000000..78d5ae743Binary files /dev/null and b/apps/web/public/docs/guides/latency-ci-integration-test/github-api-token.png differdiff --git a/apps/web/public/docs/guides/latency-ci-integration-test/openstatus-api-token.png b/apps/web/public/docs/guides/latency-ci-integration-test/openstatus-api-token.pngnew file mode 100644index 000000000..c86536c9fBinary files /dev/null and b/apps/web/public/docs/guides/latency-ci-integration-test/openstatus-api-token.png differdiff --git a/apps/web/public/docs/guides/self-hosting-openstatus/local-openstatus.png b/apps/web/public/docs/guides/self-hosting-openstatus/local-openstatus.pngnew file mode 100644index 000000000..4bd017ae5Binary files /dev/null and b/apps/web/public/docs/guides/self-hosting-openstatus/local-openstatus.png differdiff --git a/apps/web/public/docs/houston.webp b/apps/web/public/docs/houston.webpnew file mode 100644index 000000000..930c16497Binary files /dev/null and b/apps/web/public/docs/houston.webp differdiff --git a/apps/web/public/docs/icon.png b/apps/web/public/docs/icon.pngnew file mode 100644index 000000000..9f458a6c8Binary files /dev/null and b/apps/web/public/docs/icon.png differdiff --git a/apps/web/public/docs/incident/incident-detail.png b/apps/web/public/docs/incident/incident-detail.pngnew file mode 100644index 000000000..392b810d4Binary files /dev/null and b/apps/web/public/docs/incident/incident-detail.png differdiff --git a/apps/web/public/docs/monitor/assertions.png b/apps/web/public/docs/monitor/assertions.pngnew file mode 100644index 000000000..0f26cc025Binary files /dev/null and b/apps/web/public/docs/monitor/assertions.png differdiff --git a/apps/web/public/docs/monitor/clone-monitor.png b/apps/web/public/docs/monitor/clone-monitor.pngnew file mode 100644index 000000000..27e9bfb92Binary files /dev/null and b/apps/web/public/docs/monitor/clone-monitor.png differdiff --git a/apps/web/public/docs/monitor/create-monitor.png b/apps/web/public/docs/monitor/create-monitor.pngnew file mode 100644index 000000000..dcd013fe7Binary files /dev/null and b/apps/web/public/docs/monitor/create-monitor.png differdiff --git a/apps/web/public/docs/monitor/create-tag.png b/apps/web/public/docs/monitor/create-tag.pngnew file mode 100644index 000000000..7984f1916Binary files /dev/null and b/apps/web/public/docs/monitor/create-tag.png differdiff --git a/apps/web/public/docs/monitor/filter-tag.png b/apps/web/public/docs/monitor/filter-tag.pngnew file mode 100644index 000000000..abd612a97Binary files /dev/null and b/apps/web/public/docs/monitor/filter-tag.png differdiff --git a/apps/web/public/docs/monitor/http-monitor.png b/apps/web/public/docs/monitor/http-monitor.pngnew file mode 100644index 000000000..d2d0358ceBinary files /dev/null and b/apps/web/public/docs/monitor/http-monitor.png differdiff --git a/apps/web/public/docs/monitor/monitor-detail.png b/apps/web/public/docs/monitor/monitor-detail.pngnew file mode 100644index 000000000..2ba4b2a26Binary files /dev/null and b/apps/web/public/docs/monitor/monitor-detail.png differdiff --git a/apps/web/public/docs/monitor/monitor.png b/apps/web/public/docs/monitor/monitor.pngnew file mode 100644index 000000000..ecbda963fBinary files /dev/null and b/apps/web/public/docs/monitor/monitor.png differdiff --git a/apps/web/public/docs/monitor/notifications.png b/apps/web/public/docs/monitor/notifications.pngnew file mode 100644index 000000000..7343a6595Binary files /dev/null and b/apps/web/public/docs/monitor/notifications.png differdiff --git a/apps/web/public/docs/monitor/overview.png b/apps/web/public/docs/monitor/overview.pngnew file mode 100644index 000000000..eccb4cfabBinary files /dev/null and b/apps/web/public/docs/monitor/overview.png differdiff --git a/apps/web/public/docs/monitor/overview/dashboard.png b/apps/web/public/docs/monitor/overview/dashboard.pngnew file mode 100644index 000000000..841de33acBinary files /dev/null and b/apps/web/public/docs/monitor/overview/dashboard.png differdiff --git a/apps/web/public/docs/monitor/public-monitor.png b/apps/web/public/docs/monitor/public-monitor.pngnew file mode 100644index 000000000..4636e404dBinary files /dev/null and b/apps/web/public/docs/monitor/public-monitor.png differdiff --git a/apps/web/public/docs/monitor/response-log-header.png b/apps/web/public/docs/monitor/response-log-header.pngnew file mode 100644index 000000000..0e862bc9cBinary files /dev/null and b/apps/web/public/docs/monitor/response-log-header.png differdiff --git a/apps/web/public/docs/monitor/response-log-timing.png b/apps/web/public/docs/monitor/response-log-timing.pngnew file mode 100644index 000000000..2185ab137Binary files /dev/null and b/apps/web/public/docs/monitor/response-log-timing.png differdiff --git a/apps/web/public/docs/monitor/response-log.png b/apps/web/public/docs/monitor/response-log.pngnew file mode 100644index 000000000..14cc719efBinary files /dev/null and b/apps/web/public/docs/monitor/response-log.png differdiff --git a/apps/web/public/docs/monitor/setting-public-monitor.png b/apps/web/public/docs/monitor/setting-public-monitor.pngnew file mode 100644index 000000000..d1b0f8281Binary files /dev/null and b/apps/web/public/docs/monitor/setting-public-monitor.png differdiff --git a/apps/web/public/docs/monitor/tcp-monitor.png b/apps/web/public/docs/monitor/tcp-monitor.pngnew file mode 100644index 000000000..97541fb8cBinary files /dev/null and b/apps/web/public/docs/monitor/tcp-monitor.png differdiff --git a/apps/web/public/docs/notification/discord-notification.png b/apps/web/public/docs/notification/discord-notification.pngnew file mode 100644index 000000000..850c8a848Binary files /dev/null and b/apps/web/public/docs/notification/discord-notification.png differdiff --git a/apps/web/public/docs/notification/opsgenie/opsgenie-1.png b/apps/web/public/docs/notification/opsgenie/opsgenie-1.pngnew file mode 100644index 000000000..2cf8110dbBinary files /dev/null and b/apps/web/public/docs/notification/opsgenie/opsgenie-1.png differdiff --git a/apps/web/public/docs/notification/opsgenie/opsgenie-2.png b/apps/web/public/docs/notification/opsgenie/opsgenie-2.pngnew file mode 100644index 000000000..eebeca54eBinary files /dev/null and b/apps/web/public/docs/notification/opsgenie/opsgenie-2.png differdiff --git a/apps/web/public/docs/notification/opsgenie/opsgenie-3.png b/apps/web/public/docs/notification/opsgenie/opsgenie-3.pngnew file mode 100644index 000000000..3be659fe6Binary files /dev/null and b/apps/web/public/docs/notification/opsgenie/opsgenie-3.png differdiff --git a/apps/web/public/docs/notification/opsgenie/opsgenie-4.png b/apps/web/public/docs/notification/opsgenie/opsgenie-4.pngnew file mode 100644index 000000000..9ed138986Binary files /dev/null and b/apps/web/public/docs/notification/opsgenie/opsgenie-4.png differdiff --git a/apps/web/public/docs/notification/opsgenie/opsgenie-5.png b/apps/web/public/docs/notification/opsgenie/opsgenie-5.pngnew file mode 100644index 000000000..f943308d0Binary files /dev/null and b/apps/web/public/docs/notification/opsgenie/opsgenie-5.png differdiff --git a/apps/web/public/docs/notification/pagerduty/pagerduty-1.png b/apps/web/public/docs/notification/pagerduty/pagerduty-1.pngnew file mode 100644index 000000000..f91f8f531Binary files /dev/null and b/apps/web/public/docs/notification/pagerduty/pagerduty-1.png differdiff --git a/apps/web/public/docs/notification/pagerduty/pagerduty-2.png b/apps/web/public/docs/notification/pagerduty/pagerduty-2.pngnew file mode 100644index 000000000..ac2f11371Binary files /dev/null and b/apps/web/public/docs/notification/pagerduty/pagerduty-2.png differdiff --git a/apps/web/public/docs/notification/pagerduty/pagerduty-3.png b/apps/web/public/docs/notification/pagerduty/pagerduty-3.pngnew file mode 100644index 000000000..3b00e96feBinary files /dev/null and b/apps/web/public/docs/notification/pagerduty/pagerduty-3.png differdiff --git a/apps/web/public/docs/setup-env/clerk-step1.png b/apps/web/public/docs/setup-env/clerk-step1.pngnew file mode 100644index 000000000..4bed790d1Binary files /dev/null and b/apps/web/public/docs/setup-env/clerk-step1.png differdiff --git a/apps/web/public/docs/setup-env/clerk-step2.png b/apps/web/public/docs/setup-env/clerk-step2.pngnew file mode 100644index 000000000..82aca38a5Binary files /dev/null and b/apps/web/public/docs/setup-env/clerk-step2.png differdiff --git a/apps/web/public/docs/setup-env/clerk-step3.png b/apps/web/public/docs/setup-env/clerk-step3.pngnew file mode 100644index 000000000..b6a4f54acBinary files /dev/null and b/apps/web/public/docs/setup-env/clerk-step3.png differdiff --git a/apps/web/public/docs/setup-env/clerk.png b/apps/web/public/docs/setup-env/clerk.pngnew file mode 100644index 000000000..3814bcd8eBinary files /dev/null and b/apps/web/public/docs/setup-env/clerk.png differdiff --git a/apps/web/public/docs/setup-env/drizzle-studio.png b/apps/web/public/docs/setup-env/drizzle-studio.pngnew file mode 100644index 000000000..64984daeaBinary files /dev/null and b/apps/web/public/docs/setup-env/drizzle-studio.png differdiff --git a/apps/web/public/docs/setup-env/resend.png b/apps/web/public/docs/setup-env/resend.pngnew file mode 100644index 000000000..9b4650560Binary files /dev/null and b/apps/web/public/docs/setup-env/resend.png differdiff --git a/apps/web/public/docs/setup-env/tinybird.png b/apps/web/public/docs/setup-env/tinybird.pngnew file mode 100644index 000000000..48e6082d1Binary files /dev/null and b/apps/web/public/docs/setup-env/tinybird.png differdiff --git a/apps/web/public/docs/status-page/create-status-page.png b/apps/web/public/docs/status-page/create-status-page.pngnew file mode 100644index 000000000..1afa03ef8Binary files /dev/null and b/apps/web/public/docs/status-page/create-status-page.png differdiff --git a/apps/web/public/docs/status-page/description.png b/apps/web/public/docs/status-page/description.pngnew file mode 100644index 000000000..8cff52595Binary files /dev/null and b/apps/web/public/docs/status-page/description.png differdiff --git a/apps/web/public/docs/status-page/favicon.png b/apps/web/public/docs/status-page/favicon.pngnew file mode 100644index 000000000..8aa95339fBinary files /dev/null and b/apps/web/public/docs/status-page/favicon.png differdiff --git a/apps/web/public/docs/status-page/status-page-empty.png b/apps/web/public/docs/status-page/status-page-empty.pngnew file mode 100644index 000000000..d24e72b75Binary files /dev/null and b/apps/web/public/docs/status-page/status-page-empty.png differdiff --git a/apps/web/public/docs/status-page/status-page.png b/apps/web/public/docs/status-page/status-page.pngnew file mode 100644index 000000000..0fbd18e5bBinary files /dev/null and b/apps/web/public/docs/status-page/status-page.png differdiff --git a/apps/web/public/docs/status-widget/widget-example.png b/apps/web/public/docs/status-widget/widget-example.pngnew file mode 100644index 000000000..25c87a619Binary files /dev/null and b/apps/web/public/docs/status-widget/widget-example.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/configure-status-page-1.png b/apps/web/public/docs/tutorial/configure-status-page/configure-status-page-1.pngnew file mode 100644index 000000000..d875f4c28Binary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/configure-status-page-1.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-1.png b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-1.pngnew file mode 100644index 000000000..f084193acBinary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-1.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-2.png b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-2.pngnew file mode 100644index 000000000..378c08e2aBinary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-2.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-3.png b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-3.pngnew file mode 100644index 000000000..def4f80bfBinary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-3.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-4.png b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-4.pngnew file mode 100644index 000000000..f088fd6b7Binary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/status-page-beta-4.png differdiff --git a/apps/web/public/docs/tutorial/configure-status-page/status-page-floating.png b/apps/web/public/docs/tutorial/configure-status-page/status-page-floating.pngnew file mode 100644index 000000000..01b9f4235Binary files /dev/null and b/apps/web/public/docs/tutorial/configure-status-page/status-page-floating.png differdiff --git a/apps/web/public/docs/tutorial/create-monitor/create-monitor-1.png b/apps/web/public/docs/tutorial/create-monitor/create-monitor-1.pngnew file mode 100644index 000000000..790b7b5eeBinary files /dev/null and b/apps/web/public/docs/tutorial/create-monitor/create-monitor-1.png differdiff --git a/apps/web/public/docs/tutorial/create-monitor/create-monitor-2.png b/apps/web/public/docs/tutorial/create-monitor/create-monitor-2.pngnew file mode 100644index 000000000..33ad323c7Binary files /dev/null and b/apps/web/public/docs/tutorial/create-monitor/create-monitor-2.png differdiff --git a/apps/web/public/docs/tutorial/create-monitor/monitor-overview.png b/apps/web/public/docs/tutorial/create-monitor/monitor-overview.pngnew file mode 100644index 000000000..b6a35b375Binary files /dev/null and b/apps/web/public/docs/tutorial/create-monitor/monitor-overview.png differdiff --git a/apps/web/public/docs/tutorial/create-status-page/create-status-page-1.png b/apps/web/public/docs/tutorial/create-status-page/create-status-page-1.pngnew file mode 100644index 000000000..1ae8b63deBinary files /dev/null and b/apps/web/public/docs/tutorial/create-status-page/create-status-page-1.png differdiff --git a/apps/web/public/docs/tutorial/create-status-page/create-status-page-2.png b/apps/web/public/docs/tutorial/create-status-page/create-status-page-2.pngnew file mode 100644index 000000000..f01747f84Binary files /dev/null and b/apps/web/public/docs/tutorial/create-status-page/create-status-page-2.png differdiff --git a/apps/web/public/docs/tutorial/get-started-with-openstatus-cli/CLI.png b/apps/web/public/docs/tutorial/get-started-with-openstatus-cli/CLI.pngnew file mode 100644index 000000000..20c6df035Binary files /dev/null and b/apps/web/public/docs/tutorial/get-started-with-openstatus-cli/CLI.png differdiff --git a/apps/web/src/app/(ai)/llms.txt/route.ts b/apps/web/src/app/(ai)/llms.txt/route.tsindex 53c007c99..6bc1cf36f 100644--- a/apps/web/src/app/(ai)/llms.txt/route.ts+++ b/apps/web/src/app/(ai)/llms.txt/route.ts@@ -7,6 +7,7 @@ import {getBlogPosts,getChangelogPosts,getComparePages,+ getDocPages,getGuides,getProductPages,getToolingPages,@@ -58,6 +59,10 @@ export function GET() {"Tooling",getToolingPages().map((p) => toItem(p, true)),),+ renderSection(+ "Documentation",+ getDocPages().map((p) => toItem(p, true)),+ ),renderSection("Guides",getGuides().map((p) => toItem(p, true)),@@ -91,9 +96,6 @@ export function GET() {"## Optional","","- [API OpenAPI](https://api.openstatus.dev/openapi)",- "- [Documentation](https://docs.openstatus.dev/)",- "- [Documentation llms.txt](https://docs.openstatus.dev/llms.txt)",- "- [Documentation llms-full.txt](https://docs.openstatus.dev/llms-full.txt)","- [GitHub](https://github.com/openstatushq/openstatus)","- [SDK (JSR)](https://jsr.io/@openstatus/sdk-node)","- [Theme Store](https://themes.openstatus.dev)",diff --git a/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsx b/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsxnew file mode 100644index 000000000..839f74d11--- /dev/null+++ b/apps/web/src/app/(docs)/docs/[[...slug]]/page.tsx@@ -0,0 +1,176 @@+import {+ ContentBoxDescription,+ ContentBoxLink,+ ContentBoxTitle,+} from "@/app/(landing)/content-box";+import { ContentPagination } from "@/app/(landing)/content-pagination";+import {+ getDocs,+ getDocsPage,+ getDocsPagination,+ gitLastModified,+ validateDocsNav,+} from "@/content/docs";+import { DocsSubNav } from "@/content/docs-sub-nav";+import { TableOfContents } from "@/content/docs-toc";+import {+ type DocsNavNode,+ docsNavTree,+ findDocsNode,+ getDocsContainerSlugs,+} from "@/content/docs.config";+import { CustomMDX } from "@/content/mdx";+import { Grid } from "@/content/mdx-components/grid";+import { extractHeadings } from "@/content/toc";+import { BASE_URL } from "@/lib/metadata/shared-metadata";+import type { Metadata } from "next";+import { notFound } from "next/navigation";++export const dynamicParams = false;++const EDIT_BASE =+ "https://github.com/openstatusHQ/openstatus/edit/main/apps/web/src/content/pages/docs";++type Params = { slug?: string[] };++export function generateStaticParams(): Params[] {+ const { errors, warnings } = validateDocsNav();+ for (const w of warnings) console.warn(`[docs] ${w}`);+ if (errors.length > 0) {+ const message = `docs nav validation failed:\n${errors.join("\n")}`;+ if (process.env.NODE_ENV === "production") throw new Error(message);+ for (const e of errors) console.warn(`[docs] ERROR ${e}`);+ }+ return [+ { slug: [] },+ ...getDocsContainerSlugs().map((s) => ({ slug: s.split("/") })),+ ...getDocs().map((d) => ({ slug: d.slug.split("/") })),+ ];+}++export async function generateMetadata({+ params,+}: {+ params: Promise<Params>;+}): Promise<Metadata | undefined> {+ const { slug } = await params;+ if (!slug || slug.length === 0) {+ return {+ title: "openstatus documentation",+ description:+ "Learn how to create your status page, monitor your endpoints, and configure notifications with openstatus.",+ alternates: { canonical: `${BASE_URL}/docs` },+ };+ }+ const joined = slug.join("/");+ const doc = getDocsPage(joined);+ if (!doc) {+ const node = findDocsNode(docsNavTree(), `/docs/${joined}`);+ if (node?.children?.length) {+ return {+ title: `${node.label} — openstatus docs`,+ alternates: { canonical: `${BASE_URL}/docs/${joined}` },+ };+ }+ return;+ }+ return {+ title: doc.metadata.title,+ description: doc.metadata.description,+ alternates: { canonical: `${BASE_URL}${doc.href}` },+ };+}++// A container node (the /docs hub or a section) → one card per child. Same nav+// tree the markdown listing walks, so HTML and markdown can't drift.+function DocsContainerLanding({ node }: { node: DocsNavNode }) {+ return (+ <div className="min-w-0 flex-1 space-y-8">+ <DocsSubNav />+ <section className="prose dark:prose-invert max-w-none">+ <h1>{node.label}</h1>+ {node.description ? <p>{node.description}</p> : null}+ <Grid cols={2}>+ {node.children?.map((card) => {+ const description = card.slug+ ? getDocsPage(card.slug)?.metadata.description+ : undefined;+ return (+ <ContentBoxLink key={card.href} href={card.href}>+ <ContentBoxTitle>{card.label}</ContentBoxTitle>+ {description ? (+ <ContentBoxDescription>{description}</ContentBoxDescription>+ ) : null}+ </ContentBoxLink>+ );+ })}+ </Grid>+ </section>+ </div>+ );+}++export default async function DocsPage({+ params,+}: {+ params: Promise<Params>;+}) {+ const { slug } = await params;+ const joined = slug?.join("/") ?? "";++ const doc = joined ? getDocsPage(joined) : undefined;+ if (!doc) {+ const node = findDocsNode(+ docsNavTree(),+ joined ? `/docs/${joined}` : "/docs",+ );+ if (node?.children?.length) return <DocsContainerLanding node={node} />;+ notFound();+ }++ const toc = extractHeadings(doc.content);+ const { prev, next } = getDocsPagination(joined);+ const lastUpdated = gitLastModified(doc.filePath);++ return (+ <div className="flex gap-8">+ <div className="min-w-0 flex-1 space-y-8">+ <DocsSubNav />+ <article className="prose dark:prose-invert max-w-none">+ <h1>{doc.metadata.title}</h1>+ <CustomMDX source={doc.content} />+ </article>+ <div className="space-y-4">+ <div className="flex flex-row flex-wrap justify-between gap-x-4 gap-y-2 text-muted-foreground text-sm">+ <a+ href={`${EDIT_BASE}/${joined}.mdx`}+ target="_blank"+ rel="noopener noreferrer"+ className="ease transition-colors duration-150 hover:text-foreground motion-reduce:transition-none"+ >+ Edit this page on GitHub+ </a>+ {lastUpdated ? (+ <span>+ Last updated{" "}+ {lastUpdated.toLocaleDateString("en-us", {+ month: "short",+ day: "2-digit",+ year: "numeric",+ })}+ </span>+ ) : null}+ </div>++ <ContentPagination prev={prev} next={next} />+ </div>+ </div>++ <aside className="hidden w-56 shrink-0 xl:block">+ <div className="sticky top-4 max-h-[calc(100vh-2rem)] overflow-y-auto">+ <TableOfContents items={toc} />+ </div>+ </aside>+ </div>+ );+}diff --git a/apps/web/src/app/(docs)/layout.tsx b/apps/web/src/app/(docs)/layout.tsxnew file mode 100644index 000000000..153bdd8b1--- /dev/null+++ b/apps/web/src/app/(docs)/layout.tsx@@ -0,0 +1,23 @@+import { DocsFooter } from "@/content/docs-footer";+import { DocsHeader } from "@/content/docs-header";+import { DocsMobileNav, DocsSidebar } from "@/content/docs-sidebar";++export default function DocsLayout({+ children,+}: {+ children: React.ReactNode;+}) {+ return (+ <div className="mx-auto flex min-h-screen max-w-7xl flex-col gap-4 font-sans">+ <DocsHeader />+ <div className="flex flex-1 gap-8 px-4 py-4">+ <DocsSidebar className="hidden w-56 shrink-0 lg:block" />+ <main className="min-w-0 flex-1">+ <DocsMobileNav className="lg:hidden" />+ {children}+ </main>+ </div>+ <DocsFooter />+ </div>+ );+}diff --git a/apps/web/src/app/(landing)/(redirect)/docs/page.tsx b/apps/web/src/app/(landing)/(redirect)/docs/page.tsxdeleted file mode 100644index 415541f6a..000000000--- a/apps/web/src/app/(landing)/(redirect)/docs/page.tsx+++ /dev/null@@ -1,5 +0,0 @@-import { redirect } from "next/navigation";--export default function DiscordRedirect() {- return redirect("https://docs.openstatus.dev");-}diff --git a/apps/web/src/app/(landing)/blog/[slug]/page.tsx b/apps/web/src/app/(landing)/blog/[slug]/page.tsxindex 8cf474de0..0e3ddc6b3 100644--- a/apps/web/src/app/(landing)/blog/[slug]/page.tsx+++ b/apps/web/src/app/(landing)/blog/[slug]/page.tsx@@ -97,11 +97,7 @@ export default async function Blog({</div>) : null}<CustomMDX source={post.content} />- <ContentPagination- previousPost={previousPost}- nextPost={nextPost}- prefix="/blog"- />+ <ContentPagination prev={previousPost} next={nextPost} /></section>);}diff --git a/apps/web/src/app/(landing)/changelog/[slug]/page.tsx b/apps/web/src/app/(landing)/changelog/[slug]/page.tsxindex dba250a7e..53fe9a226 100644--- a/apps/web/src/app/(landing)/changelog/[slug]/page.tsx+++ b/apps/web/src/app/(landing)/changelog/[slug]/page.tsx@@ -97,11 +97,7 @@ export default async function Changelog({</div>) : null}<CustomMDX source={post.content} />- <ContentPagination- previousPost={previousPost}- nextPost={nextPost}- prefix="/changelog"- />+ <ContentPagination prev={previousPost} next={nextPost} /></section>);}diff --git a/apps/web/src/app/(landing)/compare/[slug]/page.tsx b/apps/web/src/app/(landing)/compare/[slug]/page.tsxindex 261756e15..ef5ee1bc4 100644--- a/apps/web/src/app/(landing)/compare/[slug]/page.tsx+++ b/apps/web/src/app/(landing)/compare/[slug]/page.tsx@@ -86,11 +86,7 @@ export default async function Blog({<h1>{post.metadata.title}</h1><p className="text-lg">{post.metadata.description}</p><CustomMDX source={post.content} />- <ContentPagination- previousPost={previousPost}- nextPost={nextPost}- prefix="/compare"- />+ <ContentPagination prev={previousPost} next={nextPost} /></section>);}diff --git a/apps/web/src/app/(landing)/content-pagination.tsx b/apps/web/src/app/(landing)/content-pagination.tsxindex 20896ac12..46de294bd 100644--- a/apps/web/src/app/(landing)/content-pagination.tsx+++ b/apps/web/src/app/(landing)/content-pagination.tsx@@ -1,37 +1,36 @@-import { Link } from "@/content/link";import type { MDXData } from "@/content/utils";+import Link from "next/link";export function ContentPagination({- previousPost,- nextPost,- prefix,+ prev,+ next,}: {- previousPost?: MDXData;- nextPost?: MDXData;- prefix: string;+ prev?: MDXData;+ next?: MDXData;}) {+ if (!prev && !next) return null;return (- <div className="flex items-center justify-between gap-8">- <p className="flex-1 truncate">- {previousPost ? (- <Link- href={`${prefix}/${previousPost.slug}`}- className="max-w-40 truncate"- >- {previousPost.metadata.title}- </Link>- ) : null}- </p>- <p className="flex-1 truncate text-right">- {nextPost ? (- <Link- href={`${prefix}/${nextPost.slug}`}- className="max-w-40 truncate"- >- {nextPost.metadata.title}- </Link>- ) : null}- </p>+ <div className="[&>a]:ease grid grid-cols-2 gap-px border border-border bg-border [&>*]:bg-background [&>a]:p-4 [&>a]:transition-colors [&>a]:duration-150 [&>a]:hover:bg-muted [&>a]:motion-reduce:transition-none">+ {prev ? (+ <Link href={prev.href} className="no-underline! ">+ <span className="block text-muted-foreground">Previous</span>+ <span className="font-medium text-foreground">+ {prev.metadata.title}+ </span>+ </Link>+ ) : (+ <span />+ )}+ {next ? (+ <Link href={next.href} className="no-underline! text-right">+ <span className="block text-muted-foreground">Next</span>+ <span className="font-medium text-foreground">+ {next.metadata.title}+ </span>+ </Link>+ ) : (+ <span />+ )}</div>);}diff --git a/apps/web/src/app/(landing)/guides/[slug]/page.tsx b/apps/web/src/app/(landing)/guides/[slug]/page.tsxindex 2d6f0f3e6..a3ed7ae12 100644--- a/apps/web/src/app/(landing)/guides/[slug]/page.tsx+++ b/apps/web/src/app/(landing)/guides/[slug]/page.tsx@@ -97,11 +97,7 @@ export default async function Guide({</div>) : null}<CustomMDX source={post.content} />- <ContentPagination- previousPost={previousPost}- nextPost={nextPost}- prefix="/guides"- />+ <ContentPagination prev={previousPost} next={nextPost} /></section>);}diff --git a/apps/web/src/app/(landing)/use-case/[slug]/page.tsx b/apps/web/src/app/(landing)/use-case/[slug]/page.tsxindex 51acdef82..b23fed981 100644--- a/apps/web/src/app/(landing)/use-case/[slug]/page.tsx+++ b/apps/web/src/app/(landing)/use-case/[slug]/page.tsx@@ -97,11 +97,7 @@ export default async function UseCase({</div>) : null}<CustomMDX source={post.content} />- <ContentPagination- previousPost={previousPost}- nextPost={nextPost}- prefix="/use-case"- />+ <ContentPagination prev={previousPost} next={nextPost} /></section>);}diff --git a/apps/web/src/app/api/markdown/[[...path]]/route.ts b/apps/web/src/app/api/markdown/[[...path]]/route.tsindex 5b4e95379..13875ce0c 100644--- a/apps/web/src/app/api/markdown/[[...path]]/route.ts+++ b/apps/web/src/app/api/markdown/[[...path]]/route.ts@@ -1,9 +1,9 @@import { convertMdxToMarkdown } from "@/content/convert";-import { resolveContent } from "@/content/resolve";import {generateStatusDetailMarkdown,generateStatusIndexMarkdown,} from "@/content/status-markdown";+import { resolveContent } from "@/content/utils/resolve";import { type NextRequest, NextResponse } from "next/server";export const runtime = "nodejs"; // Need fs access for content loadingdiff --git a/apps/web/src/app/api/search/route.ts b/apps/web/src/app/api/search/route.tsindex 0f2498569..3806a40fd 100644--- a/apps/web/src/app/api/search/route.ts+++ b/apps/web/src/app/api/search/route.ts@@ -74,6 +74,7 @@ function search(params: SearchParams) {...getPages("guides"),...getPages("use-case"),...getPages("unrelated"),+ ...getPages("docs"),home,];} else {diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsxindex 2a53c414b..4a7ecfe93 100644--- a/apps/web/src/app/layout.tsx+++ b/apps/web/src/app/layout.tsx@@ -4,6 +4,7 @@ import { OpenPanelComponent } from "@openpanel/nextjs";import type { Metadata } from "next";import { Inter } from "next/font/google";import LocalFont from "next/font/local";+import Script from "next/script";import { ThemeProvider } from "@/components/theme-provider";import { WebMcpProvider } from "@/components/webmcp-provider";@@ -18,7 +19,7 @@ import { Toaster } from "@openstatus/ui/components/ui/sonner";import PlausibleProvider from "next-plausible";import { NuqsAdapter } from "nuqs/adapters/next/app";-const inter = Inter({ subsets: ["latin"] });+const inter = Inter({ subsets: ["latin"], variable: "--font-sans" });const calSans = LocalFont({src: "../public/fonts/CalSans-SemiBold.ttf",@@ -46,7 +47,7 @@ export default function RootLayout({className={`${inter.className// biome-ignore lint/nursery/useSortedClasses: <explanation>- } ${calSans.variable}`}+ } ${inter.variable} ${calSans.variable} antialiased`}><PlausibleProvider domain="openstatus.dev"><ThemeProvider attribute="class" defaultTheme="light" enableSystem>@@ -86,6 +87,7 @@ export default function RootLayout({}}richColors/>+ <Script src="https://ui.sh/ui-picker.js" /></body></html>);diff --git a/apps/web/src/app/sitemap.ts b/apps/web/src/app/sitemap.tsindex cd94b6f4b..cde9ae6c8 100644--- a/apps/web/src/app/sitemap.ts+++ b/apps/web/src/app/sitemap.ts@@ -3,6 +3,7 @@ import {getChangelogPosts,getComparePages,getCustomerPages,+ getDocPages,getGuides,getHomePage,getProductPages,@@ -31,6 +32,7 @@ const allGuides = getGuides();const allUseCases = getUseCasePages();const allTooling = getToolingPages();const allCustomers = getCustomerPages();+const allDocs = getDocPages();export default async function sitemap(): Promise<MetadataRoute.Sitemap> {const externalServices = await cachedListExternalServices();@@ -219,6 +221,22 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {priority: 0.7,}));+ const docs = allDocs.map((page) => ({+ url: `https://www.openstatus.dev/docs/${page.slug}`,+ lastModified: page.metadata.publishedAt,+ changeFrequency: "monthly" as const,+ priority: 0.7,+ }));++ const docsIndex = [+ {+ url: "https://www.openstatus.dev/docs",+ lastModified: new Date().toISOString().slice(0, 10),+ changeFrequency: "weekly" as const,+ priority: 0.8,+ },+ ];+return [...home,...blogs,@@ -239,6 +257,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {...toolingIndex,...customers,...customersIndex,+ ...docs,+ ...docsIndex,...externalServicesIndex,...externalServiceEntries,...externalServiceComponentEntries,diff --git a/apps/web/src/content/cmdk.tsx b/apps/web/src/content/cmdk.tsxindex 56326ca97..5c9808799 100644--- a/apps/web/src/content/cmdk.tsx+++ b/apps/web/src/content/cmdk.tsx@@ -67,10 +67,16 @@ const CONFIG: ConfigSection[] = [label: "Go to Pricing",href: "/pricing",},+ {+ type: "group",+ label: "Search in Docs...",+ heading: "Docs",+ page: "docs",+ },{type: "item",label: "Go to Docs",- href: "https://docs.openstatus.dev",+ href: "/docs",},{type: "item",@@ -183,13 +189,18 @@ const CONFIG: ConfigSection[] = [},];-export function CmdK() {+export function CmdK({+ defaultPage,+ className,+}: { defaultPage?: string; className?: string } = {}) {const [open, setOpen] = React.useState(false);const inputRef = React.useRef<HTMLInputElement | null>(null);const listRef = React.useRef<HTMLDivElement | null>(null);const resetTimerRef = React.useRef<NodeJS.Timeout | undefined>(undefined);const [search, setSearch] = React.useState("");- const [pages, setPages] = React.useState<string[]>([]);+ const [pages, setPages] = React.useState<string[]>(+ defaultPage ? [defaultPage] : [],+ );const debouncedSearch = useDebounce(search, 300);const router = useRouter();@@ -264,7 +275,7 @@ export function CmdK() {}resetTimerRef.current = setTimeout(() => {setSearch("");- setPages([]);+ setPages(defaultPage ? [defaultPage] : []);}, DELAY);}@@ -278,7 +289,7 @@ export function CmdK() {clearTimeout(resetTimerRef.current);}};- }, [open, items.length]);+ }, [open, items.length, defaultPage]);return (<>@@ -287,6 +298,7 @@ export function CmdK() {className={cn("flex w-full items-center text-left hover:bg-muted",open && "bg-muted!",+ className,)}onClick={() => setOpen(true)}>diff --git a/apps/web/src/content/convert.ts b/apps/web/src/content/convert.tsindex b56af9af0..2abe978eb 100644--- a/apps/web/src/content/convert.ts+++ b/apps/web/src/content/convert.ts@@ -83,7 +83,57 @@ export function convertMdxToMarkdown(data: MDXData): string {"<!-- SimpleChart omitted -->",);- // Step 7: Extract text from <Grid> containers (remove Grid wrapper, keep content)+ // Step 7: Convert <Aside> to a blockquote callout+ const asideLabels: Record<string, string> = {+ note: "Note",+ tip: "Tip",+ caution: "Caution",+ danger: "Danger",+ };+ markdown = markdown.replace(+ /<Aside\b([^>]*)>([\s\S]*?)<\/Aside>/g,+ (_match, attrs, content) => {+ const type = attrs.match(/type="([^"]*)"/)?.[1] ?? "note";+ const label =+ attrs.match(/title="([^"]*)"/)?.[1] ?? asideLabels[type] ?? "Note";+ const lines = [`**${label}**`, "", ...content.trim().split("\n")];+ return lines.map((line) => (line ? `> ${line}` : ">")).join("\n");+ },+ );++ // Step 8: Convert <ShowcaseYouTube entries={[...]}> to a list of links+ markdown = markdown.replace(/<ShowcaseYouTube\b[\s\S]*?\/>/g, (match) => {+ const items: string[] = [];+ for (const entry of match.matchAll(/\{[^{}]*href:[^{}]*\}/g)) {+ const href = entry[0].match(/href:\s*['"]([^'"]+)['"]/)?.[1];+ const title = entry[0].match(/title:\s*['"]([^'"]+)['"]/)?.[1];+ if (href) items.push(`- [${title ?? "YouTube video"}](${href})`);+ }+ return items.join("\n");+ });++ // Step 9: Convert card components (unwrap grid, then serialize each card)+ markdown = markdown.replace(+ /<CardGrid[^>]*>([\s\S]*?)<\/CardGrid>/g,+ (_match, content) => content,+ );+ markdown = markdown.replace(+ /<Card\b([^>]*)>([\s\S]*?)<\/Card>/g,+ (_match, attrs, content) => {+ const title = attrs.match(/title="([^"]*)"/)?.[1];+ const body = content.trim();+ return title ? `**${title}**\n\n${body}` : body;+ },+ );+ markdown = markdown.replace(/<LinkCard\b([^>]*?)\/>/g, (_match, attrs) => {+ const title = attrs.match(/title="([^"]*)"/)?.[1] ?? "";+ const href = attrs.match(/href="([^"]*)"/)?.[1] ?? "";+ const description = attrs.match(/description="([^"]*)"/)?.[1];+ const link = `[${title}](${href})`;+ return description ? `- ${link} — ${description}` : `- ${link}`;+ });++ // Step 10: Extract text from <Grid> containers (remove Grid wrapper, keep content)markdown = markdown.replace(/<Grid[^>]*>([\s\S]*?)<\/Grid>/g,(_match, content) => {@@ -91,7 +141,7 @@ export function convertMdxToMarkdown(data: MDXData): string {},);- // Step 8: Strip generic HTML containers but extract their text+ // Step 11: Strip generic HTML containers but extract their text// This handles div, span, section, articlemarkdown = markdown.replace(/<(div|span|section|article)(?:\s+[^>]*)?>[\s\S]*?<\/\1>/g,@@ -101,7 +151,7 @@ export function convertMdxToMarkdown(data: MDXData): string {},);- // Step 9: Strip remaining unknown JSX components+ // Step 12: Strip remaining unknown JSX components// Handle paired tagsmarkdown = markdown.replace(/<[A-Z]\w*[^>]*>[\s\S]*?<\/[A-Z]\w*>/g, "");// Handle self-closing tagsdiff --git a/apps/web/src/content/copy-button.tsx b/apps/web/src/content/copy-button.tsxindex 29d5889fd..2ddbd8d40 100644--- a/apps/web/src/content/copy-button.tsx+++ b/apps/web/src/content/copy-button.tsx@@ -92,7 +92,7 @@ export function CopyDropdownButton({aria-label="Copy dropdown"><span- className="relative top-[1px] shrink-0 origin-center text-[10px] text-muted-foreground transition duration-300 group-hover:text-foreground group-data-[state=open]:rotate-180 group-data-[state=open]:text-foreground"+ className="relative top-[1px] shrink-0 origin-center font-sans text-[10px] text-muted-foreground transition duration-300 group-hover:text-foreground group-data-[state=open]:rotate-180 group-data-[state=open]:text-foreground"aria-hidden="true">▲diff --git a/apps/web/src/content/docs-footer.tsx b/apps/web/src/content/docs-footer.tsxnew file mode 100644index 000000000..014eecf25--- /dev/null+++ b/apps/web/src/content/docs-footer.tsx@@ -0,0 +1,24 @@+import { Link } from "@/content/link";+import { ThemeToggle } from "@/content/theme-toggle";+import { FooterStatus } from "./footer-status";++export function DocsFooter() {+ return (+ <footer className="font-mono">+ <div className="grid gap-px border border-border bg-border sm:grid-cols-2 md:grid-cols-3 [&>*]:bg-background">+ <Link+ href="/cal"+ className="flex w-full items-center gap-2 p-4 hover:bg-muted"+ >+ Talk to the founders+ </Link>+ <div>+ <FooterStatus />+ </div>+ <div className="sm:col-span-2 md:col-span-1">+ <ThemeToggle className="rounded-none" />+ </div>+ </div>+ </footer>+ );+}diff --git a/apps/web/src/content/docs-header.tsx b/apps/web/src/content/docs-header.tsxnew file mode 100644index 000000000..23ffd7d66--- /dev/null+++ b/apps/web/src/content/docs-header.tsx@@ -0,0 +1,18 @@+import Link from "next/link";+import { CmdK } from "./cmdk";+import { LogoWithContextMenu } from "./logo-with-context-menu";++export function DocsHeader() {+ return (+ <header className="grid grid-cols-3 gap-px border border-border bg-border font-mono lg:grid-cols-5 [&>*]:bg-background [&>*]:px-4 [&>*]:py-4 [&>*]:hover:bg-muted">+ <LogoWithContextMenu />+ <CmdK className="lg:col-span-3" defaultPage="docs" />+ <Link+ href="https://app.openstatus.dev/login"+ className="truncate text-blue-700 dark:text-blue-400"+ >+ Dashboard+ </Link>+ </header>+ );+}diff --git a/apps/web/src/content/docs-sidebar.tsx b/apps/web/src/content/docs-sidebar.tsxnew file mode 100644index 000000000..e98e19b14--- /dev/null+++ b/apps/web/src/content/docs-sidebar.tsx@@ -0,0 +1,232 @@+"use client";++import { cn } from "@/lib/utils";+import { Button } from "@openstatus/ui/components/ui/button";+import {+ Drawer,+ DrawerContent,+ DrawerTitle,+ DrawerTrigger,+} from "@openstatus/ui/components/ui/drawer";+import { Menu } from "lucide-react";+import Link from "next/link";+import { usePathname } from "next/navigation";+import { useEffect, useState } from "react";+import {+ type DocsNavGroup,+ type DocsNavItem,+ docsNav,+ isExternalItem,+ isGroupItem,+} from "./docs.config";++// A group header and its direct pages share one indent level; descending into a+// nested chapter steps in by one. Top sections and their pages stay flat at 0.+const rowIndent = (depth: number) => ({+ paddingLeft: `${0.5 + depth * 0.75}rem`,+});++function groupContainsActive(group: DocsNavGroup, pathname: string): boolean {+ return group.items.some((item) => {+ if (isExternalItem(item)) return false;+ if (isGroupItem(item)) return groupContainsActive(item, pathname);+ return pathname === `/docs/${item.slug}`;+ });+}++function CollapsibleList({+ open,+ children,+ className,+}: {+ open: boolean;+ children: React.ReactNode;+ className?: string;+}) {+ return (+ <div+ className={cn(+ "grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none",+ open ? "grid-rows-[1fr]" : "grid-rows-[0fr]",+ )}+ >+ <div className={cn("overflow-hidden", className)}>{children}</div>+ </div>+ );+}++// A collapsible group — used identically for top-level sections and nested+// chapters; only the indent depth differs.+function NavGroup({+ group,+ pathname,+ onNavigate,+ depth,+}: {+ group: DocsNavGroup;+ pathname: string;+ onNavigate?: () => void;+ depth: number;+}) {+ const containsActive = groupContainsActive(group, pathname);+ const [open, setOpen] = useState(!group.collapsed || containsActive);++ useEffect(() => {+ if (containsActive) setOpen(true);+ }, [containsActive]);++ return (+ <div>+ <button+ type="button"+ onClick={() => setOpen((v) => !v)}+ className="group ease flex w-full items-center justify-between py-2 pr-2 text-foreground transition-colors duration-150 hover:bg-muted motion-reduce:transition-none"+ style={rowIndent(depth)}+ >+ <span className="font-medium font-mono">{group.label}</span>+ <span+ className={cn(+ "relative top-[1px] shrink-0 origin-center text-[10px] text-muted-foreground transition duration-300 group-hover:text-foreground motion-reduce:transition-none",+ open && "rotate-180 text-foreground",+ )}+ aria-hidden="true"+ >+ ▲+ </span>+ </button>+ <CollapsibleList open={open}>+ <NavItems+ items={group.items}+ pathname={pathname}+ onNavigate={onNavigate}+ depth={depth}+ />+ </CollapsibleList>+ </div>+ );+}++function NavItems({+ items,+ pathname,+ onNavigate,+ depth,+}: {+ items: DocsNavItem[];+ pathname: string;+ onNavigate?: () => void;+ depth: number;+}) {+ return (+ <ul>+ {items.map((item) => {+ if (isExternalItem(item)) {+ return (+ <li key={item.link}>+ <a+ href={item.link}+ target="_blank"+ rel="noopener noreferrer"+ className="ease block py-2 pr-2 text-muted-foreground transition-colors duration-150 hover:bg-muted hover:text-foreground motion-reduce:transition-none"+ style={rowIndent(depth)}+ >+ {item.label}+ </a>+ </li>+ );+ }+ if (isGroupItem(item)) {+ return (+ <li key={item.label}>+ <NavGroup+ group={item}+ pathname={pathname}+ onNavigate={onNavigate}+ depth={depth + 1}+ />+ </li>+ );+ }+ const href = `/docs/${item.slug}`;+ const active = pathname === href;+ return (+ <li key={item.slug}>+ <Link+ href={href}+ onClick={onNavigate}+ className={cn(+ "ease block py-2 pr-2 text-muted-foreground transition-colors duration-150 hover:bg-muted hover:text-foreground motion-reduce:transition-none",+ active && "bg-muted text-foreground",+ )}+ style={rowIndent(depth)}+ >+ {item.label}+ </Link>+ </li>+ );+ })}+ </ul>+ );+}++function NavTree({+ pathname,+ onNavigate,+}: {+ pathname: string;+ onNavigate?: () => void;+}) {+ return (+ <nav aria-label="Docs" className="flex flex-col gap-1 text-sm">+ {docsNav.map((section) => (+ <NavGroup+ key={section.label}+ group={section}+ pathname={pathname}+ onNavigate={onNavigate}+ depth={0}+ />+ ))}+ </nav>+ );+}++export function DocsSidebar({ className }: { className?: string }) {+ const pathname = usePathname();+ return (+ <aside className={className}>+ <div className="sticky top-4 max-h-[calc(100vh-2rem)] overflow-y-auto">+ <NavTree pathname={pathname} />+ </div>+ </aside>+ );+}++export function DocsMobileNav({ className }: { className?: string }) {+ const pathname = usePathname();+ const [open, setOpen] = useState(false);+ return (+ <div className={className}>+ <Drawer open={open} onOpenChange={setOpen}>+ <DrawerTrigger+ aria-label="Open docs menu"+ className="fixed right-4 bottom-4 z-40"+ asChild+ >+ <Button className="h-auto rounded-none py-3 font-mono has-[>svg]:px-4">+ <Menu className="size-4" />+ Menu+ </Button>+ </DrawerTrigger>+ <DrawerContent className="rounded-none! font-sans">+ <DrawerTitle className="border-border border-b p-4 font-medium">+ Documentation+ </DrawerTitle>+ <div className="min-h-0 flex-1 overflow-y-auto p-4">+ <NavTree pathname={pathname} onNavigate={() => setOpen(false)} />+ </div>+ </DrawerContent>+ </Drawer>+ </div>+ );+}diff --git a/apps/web/src/content/docs-sub-nav.tsx b/apps/web/src/content/docs-sub-nav.tsxnew file mode 100644index 000000000..89a487aed--- /dev/null+++ b/apps/web/src/content/docs-sub-nav.tsx@@ -0,0 +1,42 @@+"use client";++import { cn } from "@/lib/utils";+import Link from "next/link";+import { usePathname } from "next/navigation";+import { Fragment } from "react";+import { CopyDropdownButton } from "./copy-button";++export function DocsSubNav({+ className,+ ...props+}: React.ComponentProps<"div">) {+ const pathname = usePathname();+ const segments = pathname.split("/").filter(Boolean).slice(0, -1);++ return (+ <div+ className={cn(+ "flex items-center justify-between gap-2 font-mono",+ className,+ )}+ {...props}+ >+ <div className="text-muted-foreground">+ {segments.map((segment, index) => (+ <Fragment key={segment}>+ <Link+ href={`/${segments.slice(0, index + 1).join("/")}`}+ className="ease transition-colors duration-150 hover:text-foreground motion-reduce:transition-none"+ >+ {segment.split("-").join(" ")}+ </Link>+ {index < segments.length - 1 ? (+ <span className="text-muted-foreground">{" | "}</span>+ ) : null}+ </Fragment>+ ))}+ </div>+ <CopyDropdownButton className="p-0" />+ </div>+ );+}diff --git a/apps/web/src/content/docs-toc.tsx b/apps/web/src/content/docs-toc.tsxnew file mode 100644index 000000000..4f4d41da0--- /dev/null+++ b/apps/web/src/content/docs-toc.tsx@@ -0,0 +1,74 @@+"use client";++import { cn } from "@/lib/utils";+import { useEffect, useState } from "react";+import type { TocItem } from "./toc";++function useActiveHeading(items: TocItem[]) {+ const [active, setActive] = useState<string>();++ useEffect(() => {+ if (items.length === 0) return;+ const visible = new Set<string>();+ const update = () => {+ const firstVisible = items.find((i) => visible.has(i.slug));+ if (firstVisible) {+ setActive(firstVisible.slug);+ return;+ }+ // Nothing in the activation band (e.g. scrolled past the last heading):+ // fall back to the last heading already scrolled above it.+ let aboveBand: string | undefined;+ for (const { slug } of items) {+ const el = document.getElementById(slug);+ if (el && el.getBoundingClientRect().top < 0) aboveBand = slug;+ }+ setActive(aboveBand);+ };+ const observer = new IntersectionObserver(+ (entries) => {+ for (const entry of entries) {+ if (entry.isIntersecting) visible.add(entry.target.id);+ else visible.delete(entry.target.id);+ }+ update();+ },+ { rootMargin: "0px 0px -70% 0px", threshold: 0 },+ );+ for (const { slug } of items) {+ const el = document.getElementById(slug);+ if (el) observer.observe(el);+ }+ return () => observer.disconnect();+ }, [items]);++ return active;+}++export function TableOfContents({ items }: { items: TocItem[] }) {+ const active = useActiveHeading(items);++ if (items.length === 0) return null;++ return (+ <nav aria-label="Table of contents" className="text-sm">+ <p className="py-2 font-medium font-mono text-foreground">On this page</p>+ <ul>+ {items.map((item) => (+ <li key={item.slug}>+ <a+ href={`#${item.slug}`}+ className={cn(+ "ease block py-2 text-muted-foreground transition-colors duration-150 hover:bg-muted hover:text-foreground motion-reduce:transition-none",+ item.depth === 2 ? "pl-2" : "pl-4",+ active === item.slug && "bg-muted text-foreground",+ )}+ >+ {item.text}+ </a>+ </li>+ ))}+ </ul>+ </nav>+ );+}diff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.tsnew file mode 100644index 000000000..0f687df0e--- /dev/null+++ b/apps/web/src/content/docs.config.ts@@ -0,0 +1,401 @@+// Single source of truth for docs section order, page order, and sidebar labels.+// Labels mirror each page's `title`, except section-landing pages which keep a+// short label (e.g. title "Foundational Concepts" → label "Overview"). Page→section+// membership is mirrored by each doc's `category` frontmatter and cross-checked+// at build time (see `validateDocsNav`).++export type DocsNavLeaf = { slug: string; label: string };+export type DocsNavExternal = { link: string; label: string; external: true };+// A chapter: a collapsible group of items, nestable to any depth. Has no slug of+// its own — its landing page (if any) is just the first child, by convention an+// "Overview" leaf — mirroring how a top-level section is rendered.+export type DocsNavGroup = {+ label: string;+ collapsed?: boolean;+ items: DocsNavItem[];+};+export type DocsNavItem = DocsNavLeaf | DocsNavExternal | DocsNavGroup;++export type DocsNavSection = DocsNavGroup;++export const DOCS_SECTIONS = [+ "Concepts",+ "Tutorials",+ "Guides",+ "SDK",+ "Reference",+ "Help",+] as const;++export type DocsSection = (typeof DOCS_SECTIONS)[number];++export const docsNav: DocsNavSection[] = [+ {+ label: "Concepts",+ items: [+ { slug: "concept/getting-started", label: "Overview" },+ {+ slug: "concept/uptime-monitoring",+ label: "Understanding Uptime Monitoring",+ },+ {+ slug: "concept/best-practices-status-page",+ label: "Building Trust with Status Pages",+ },+ {+ slug: "concept/uptime-calculation-and-values",+ label: "Uptime Calculation and Shared Values",+ },+ {+ slug: "concept/uptime-monitoring-as-code",+ label: "Understanding Monitoring as Code",+ },+ {+ slug: "concept/latency-vs-response-time",+ label: "Understanding Latency vs Response Time",+ },+ ],+ },+ {+ label: "Tutorials",+ collapsed: true,+ items: [+ { slug: "tutorial/getting-started", label: "Overview" },+ {+ slug: "tutorial/how-to-create-monitor",+ label: "Create an Uptime Monitor in 5 Minutes",+ },+ {+ slug: "tutorial/how-to-create-status-page",+ label: "Create a Status Page",+ },+ {+ slug: "tutorial/how-to-configure-status-page",+ label: "Configure Your Status Page",+ },+ {+ slug: "tutorial/how-to-create-private-location",+ label: "Create a Private Location",+ },+ {+ slug: "tutorial/get-started-with-openstatus-cli",+ label: "Get Started with openstatus CLI",+ },+ {+ slug: "tutorial/how-to-setup-slack-agent",+ label: "Set Up the openstatus Slack Agent",+ },+ {+ slug: "tutorial/how-to-connect-openstatus-to-claude-code",+ label: "Connect openstatus to Claude Code",+ },+ {+ slug: "tutorial/how-to-manage-openstatus-with-terraform-cli",+ label: "Manage Your openstatus Stack with Terraform and the CLI",+ },+ {+ slug: "tutorial/how-to-import-status-page",+ label: "Import a Status Page from Another Provider",+ },+ ],+ },+ {+ label: "Guides",+ collapsed: true,+ items: [+ { slug: "guides/getting-started", label: "Overview" },+ {+ slug: "guides/how-to-monitor-mcp-server",+ label: "How to Monitor Your Model Context Provider (MCP) Server",+ },+ {+ slug: "guides/how-to-run-synthetic-test-github-action",+ label: "How to Run Synthetic Tests in GitHub Actions",+ },+ {+ slug: "guides/how-to-export-metrics-to-otlp-endpoint",+ label: "How to Export Metrics to an OTLP Endpoint",+ },+ {+ slug: "guides/how-to-add-svg-status-badge",+ label: "How to Add a Status Badge to a GitHub README",+ },+ {+ slug: "guides/how-to-use-react-widget",+ label: "How to Use openstatus React Widget",+ },+ {+ slug: "guides/how-to-deploy-probes-cloudflare-containers",+ label: "How to Deploy a Private Probe on Cloudflare Containers",+ },+ {+ slug: "guides/self-hosting-openstatus",+ label: "How to Self-Host openstatus",+ },+ {+ slug: "guides/self-host-status-page-only",+ label: "Self-Host the openstatus Status Page (Lightweight)",+ },+ {+ slug: "guides/how-deploy-status-page-cf-pages",+ label: "How to Deploy a Status Page to Cloudflare Pages",+ },+ {+ slug: "guides/how-to-translate-status-page",+ label: "How to translate your status page",+ },+ {+ slug: "guides/how-to-embed-status-page-iframe",+ label: "How to Embed a Status Page in an Iframe",+ },+ ],+ },+ {+ label: "SDK",+ collapsed: true,+ items: [+ {+ label: "Node SDK",+ collapsed: true,+ items: [+ { slug: "sdk/nodejs/overview", label: "Overview" },+ { slug: "sdk/nodejs/getting-started", label: "Getting Started" },+ { slug: "sdk/nodejs/authentication", label: "Authentication" },+ { slug: "sdk/nodejs/monitor-service", label: "Monitor Service" },+ {+ slug: "sdk/nodejs/status-page-service",+ label: "Status Page Service",+ },+ {+ slug: "sdk/nodejs/status-report-service",+ label: "Status Report Service",+ },+ {+ slug: "sdk/nodejs/maintenance-service",+ label: "Maintenance Service",+ },+ {+ slug: "sdk/nodejs/notification-service",+ label: "Notification Service",+ },+ { slug: "sdk/nodejs/health-service", label: "Health Service" },+ { slug: "sdk/nodejs/error-handling", label: "Error Handling" },+ { slug: "sdk/nodejs/typescript-tips", label: "TypeScript Tips" },+ { slug: "sdk/nodejs/reference", label: "Reference" },+ ],+ },+ { slug: "sdk/php/overview", label: "PHP SDK" },+ { slug: "sdk/python/overview", label: "Python SDK" },+ ],+ },+ {+ label: "Reference",+ collapsed: true,+ items: [+ {+ link: "https://api.openstatus.dev/v1",+ label: "API Reference V1 - Deprecated",+ external: true,+ },+ {+ link: "https://api.openstatus.dev/openapi",+ label: "API Reference V2",+ external: true,+ },+ { slug: "reference/cli-reference", label: "CLI Reference" },+ { slug: "reference/mcp-server", label: "MCP Server" },+ { slug: "reference/dns-monitor", label: "DNS Monitor Reference" },+ { slug: "reference/http-monitor", label: "HTTP Monitor Reference" },+ { slug: "reference/incident", label: "Incident Reference" },+ { slug: "reference/tcp-monitor", label: "TCP Monitor Reference" },+ {+ slug: "reference/notification",+ label: "Notification Channels Reference",+ },+ { slug: "reference/location", label: "Location Reference" },+ {+ slug: "reference/private-location",+ label: "Private Location Reference",+ },+ { slug: "reference/status-page", label: "Status Page Reference" },+ { slug: "reference/page-components", label: "Page Components Reference" },+ { slug: "reference/status-report", label: "Status Report Reference" },+ { slug: "reference/maintenance", label: "Maintenance Reference" },+ { slug: "reference/subscriber", label: "Subscriber Reference" },+ { slug: "reference/terraform", label: "Terraform Provider Reference" },+ ],+ },+ {+ label: "Help",+ collapsed: true,+ items: [{ slug: "help/support", label: "Need help?" }],+ },+];++export function isExternalItem(item: DocsNavItem): item is DocsNavExternal {+ return "external" in item && item.external;+}++export function isGroupItem(item: DocsNavItem): item is DocsNavGroup {+ return "items" in item;+}++// First internal leaf slug in document order, descending into nested groups.+// Used to derive a section/chapter's URL parent and landing page.+export function firstLeafSlug(items: DocsNavItem[]): string | undefined {+ for (const item of items) {+ if (isExternalItem(item)) continue;+ if (isGroupItem(item)) {+ const nested = firstLeafSlug(item.items);+ if (nested) return nested;+ } else {+ return item.slug;+ }+ }+ return undefined;+}++// Flattened, in-order list of internal doc slugs — drives prev/next navigation+// and the build-time validation against the content directory. Recurses into+// nested chapters so every leaf is covered regardless of depth.+export function flattenDocsNav(): DocsNavLeaf[] {+ const walk = (items: DocsNavItem[]): DocsNavLeaf[] =>+ items.flatMap((item) => {+ if (isExternalItem(item)) return [];+ if (isGroupItem(item)) return walk(item.items);+ return [item];+ });+ return docsNav.flatMap((section) => walk(section.items));+}++// The URL segment that represents a whole section, e.g. Concepts → /docs/concept.+// Each section's items share a unique first path segment.+export function sectionParentSlug(section: DocsNavSection): string | undefined {+ return firstLeafSlug(section.items)?.split("/")[0];+}++export function sectionForParentSlug(+ parentSlug: string,+): DocsNavSection | undefined {+ return docsNav.find((s) => sectionParentSlug(s) === parentSlug);+}++// Parent/section landing slugs (concept, tutorial, …) for static generation.+export function getParentSlugs(): string[] {+ return docsNav.map(sectionParentSlug).filter((s): s is string => Boolean(s));+}++// A navigable node in the docs hierarchy (hub → sections → pages). `slug` is set+// for internal docs/sections so descriptions can be resolved lazily; `description`+// holds a node's own intro text (only the hub has one). Pure — no fs.+export type DocsNavNode = {+ label: string;+ href: string;+ slug?: string;+ description?: string;+ children?: DocsNavNode[];+};++// The whole docs hierarchy as one rooted tree, derived from `docsNav`. Drives+// path-agnostic listing: find a node by href, list its children at any depth.+export function docsNavTree(): DocsNavNode {+ return {+ label: "openstatus documentation",+ href: "/docs",+ description:+ "Learn how to create your status page, monitor your endpoints, and configure notifications.",+ children: docsNav.map((section) => {+ const parent = sectionParentSlug(section);+ return {+ label: section.label,+ // Sections own a synthetic landing at the directory root (e.g. /docs/sdk).+ href: parent ? `/docs/${parent}` : "/docs",+ slug: firstLeafSlug(section.items),+ children: section.items.map(itemToNode),+ };+ }),+ };+}++// One nav item → one tree node. A nested chapter's landing is its directory hub+// (e.g. /docs/sdk/nodejs) — a synthetic card grid, never a backing doc — so its+// pages live one level deeper (sdk/nodejs/overview, …).+function itemToNode(item: DocsNavItem): DocsNavNode {+ if (isExternalItem(item)) return { label: item.label, href: item.link };+ if (isGroupItem(item)) {+ const hub = groupHubSlug(item);+ return {+ label: item.label,+ href: hub ? `/docs/${hub}` : "/docs",+ slug: hub,+ children: item.items.map(itemToNode),+ };+ }+ return { label: item.label, href: `/docs/${item.slug}`, slug: item.slug };+}++// Every leaf slug under a set of items, descending into nested chapters.+function leafSlugs(items: DocsNavItem[]): string[] {+ return items.flatMap((item) => {+ if (isExternalItem(item)) return [];+ if (isGroupItem(item)) return leafSlugs(item.items);+ return [item.slug];+ });+}++// A chapter's hub slug: the directory shared by all its pages. The Node SDK+// chapter (pages under sdk/nodejs/*) → "sdk/nodejs".+function groupHubSlug(group: DocsNavGroup): string | undefined {+ const dirs = leafSlugs(group.items).map((s) => s.split("/").slice(0, -1));+ if (dirs.length === 0) return undefined;+ let prefix = dirs[0];+ for (const dir of dirs.slice(1)) {+ let i = 0;+ while (i < prefix.length && prefix[i] === dir[i]) i++;+ prefix = prefix.slice(0, i);+ }+ return prefix.length ? prefix.join("/") : undefined;+}++// Slugs of every container node (sections + chapters) — the synthetic hub URLs+// that have no backing MDX file and must be statically generated as card grids.+export function getDocsContainerSlugs(): string[] {+ const out: string[] = [];+ const walk = (node: DocsNavNode) => {+ for (const child of node.children ?? []) {+ if (!child.children?.length) continue;+ const slug = child.href.replace(/^\/docs\/?/, "");+ if (slug) out.push(slug);+ walk(child);+ }+ };+ walk(docsNavTree());+ return out;+}++// Depth-first lookup of a node by its href (e.g. "/docs", "/docs/concept").+export function findDocsNode(+ node: DocsNavNode,+ href: string,+): DocsNavNode | undefined {+ if (node.href === href) return node;+ for (const child of node.children ?? []) {+ const found = findDocsNode(child, href);+ if (found) return found;+ }+ return undefined;+}++// Map a slug back to its section label (the value a doc's `category` must hold).+export function sectionForSlug(slug: string): DocsSection | undefined {+ const has = (items: DocsNavItem[]): boolean =>+ items.some((i) => {+ if (isExternalItem(i)) return false;+ if (isGroupItem(i)) return has(i.items);+ return i.slug === slug;+ });+ for (const section of docsNav) {+ if (has(section.items)) return section.label as DocsSection;+ }+ return undefined;+}diff --git a/apps/web/src/content/docs.ts b/apps/web/src/content/docs.tsnew file mode 100644index 000000000..8ead11204--- /dev/null+++ b/apps/web/src/content/docs.ts@@ -0,0 +1,124 @@+import { execFileSync } from "node:child_process";+import fs from "node:fs";+import path from "node:path";+import {+ type DocsSection,+ flattenDocsNav,+ sectionForSlug,+} from "./docs.config";+import { type MDXData, parseFrontmatter } from "./utils/read";++const DOCS_DIR = path.join(process.cwd(), "src", "content", "pages", "docs");++function walkMDX(dir: string): string[] {+ if (!fs.existsSync(dir)) return [];+ return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) return walkMDX(full);+ return path.extname(entry.name) === ".mdx" ? [full] : [];+ });+}++function readDocsFile(filePath: string): MDXData {+ // Docs frontmatter omits author/publishedAt — supply defaults so the shared+ // reader validates docs identically to other MDX content.+ const { metadata, content } = parseFrontmatter(filePath, {+ author: "openstatus",+ publishedAt: fs.statSync(filePath).mtime,+ });+ const rel = path.relative(DOCS_DIR, filePath).replace(/\.mdx$/, "");+ // One file ↔ one slug. Directory landings (e.g. /docs/sdk/nodejs) are synthetic+ // card grids with no backing file — `index.mdx` is forbidden (see validateDocsNav)+ // precisely so it can't shadow a landing; use `overview.mdx` for a landing page.+ const slug = rel.split(path.sep).join("/");+ return {+ metadata,+ content,+ slug,+ href: `/docs/${slug}`,+ filePath,+ };+}++export function getDocs(): MDXData[] {+ return walkMDX(DOCS_DIR).map(readDocsFile);+}++export function getDocsPage(slug: string): MDXData | undefined {+ const direct = path.join(DOCS_DIR, `${slug}.mdx`);+ if (fs.existsSync(direct)) return readDocsFile(direct);+ return undefined;+}++// Build-time consistency check. Split by severity so an incremental migration+// can still ship: a nav slug without a file yet is an expected `warning` (not+// ported), while a category mismatch or an orphan file (a doc that exists but+// isn't in the config) is a hard `error` — a real bug on a page that IS ported.+export function validateDocsNav(): { errors: string[]; warnings: string[] } {+ const errors: string[] = [];+ const warnings: string[] = [];+ const docs = getDocs();+ const bySlug = new Map(docs.map((d) => [d.slug, d]));+ const navSlugs = new Set(flattenDocsNav().map((i) => i.slug));++ for (const { slug } of flattenDocsNav()) {+ const doc = bySlug.get(slug);+ if (!doc) {+ warnings.push(`nav references not-yet-ported doc: ${slug}`);+ continue;+ }+ const expected = sectionForSlug(slug);+ if (doc.metadata.category !== expected) {+ errors.push(+ `category mismatch for ${slug}: frontmatter "${doc.metadata.category}" ≠ config "${expected}"`,+ );+ }+ }++ for (const doc of docs) {+ if (path.basename(doc.filePath) === "index.mdx") {+ errors.push(+ `index.mdx is not allowed (it would shadow a directory landing); rename to overview.mdx: ${doc.slug}`,+ );+ }+ if (!navSlugs.has(doc.slug)) {+ errors.push(`doc not listed in docs.config.ts: ${doc.slug}`);+ }+ }++ return { errors, warnings };+}++// Prev/next from the flattened nav order (not date-sorted like blog).+export function getDocsPagination(slug: string): {+ prev?: MDXData;+ next?: MDXData;+} {+ const flat = flattenDocsNav();+ const idx = flat.findIndex((i) => i.slug === slug);+ if (idx === -1) return {};+ const toData = (item?: { slug: string }) =>+ item ? getDocsPage(item.slug) : undefined;+ return { prev: toData(flat[idx - 1]), next: toData(flat[idx + 1]) };+}++export function getDocsCategories(): DocsSection[] {+ return [+ ...new Set(getDocs().map((d) => d.metadata.category)),+ ] as DocsSection[];+}++// Last-updated from git history at build time. Returns undefined outside a git+// checkout (e.g. some CI shallow clones) so callers can fall back gracefully.+export function gitLastModified(filePath: string): Date | undefined {+ try {+ const iso = execFileSync(+ "git",+ ["log", "-1", "--format=%cI", "--", filePath],+ { encoding: "utf-8" },+ ).trim();+ return iso ? new Date(iso) : undefined;+ } catch {+ return undefined;+ }+}diff --git a/apps/web/src/content/header.tsx b/apps/web/src/content/header.tsxindex ec764954c..36b1770a1 100644--- a/apps/web/src/content/header.tsx+++ b/apps/web/src/content/header.tsx@@ -18,7 +18,7 @@ export function Header() {<DropdownMenuTrigger className="group flex items-center gap-1 data-[state=open]:bg-muted"><span className="w-full truncate text-left">{section.label}</span><span- className="relative top-[1px] shrink-0 origin-center text-[10px] text-muted-foreground transition duration-300 group-hover:text-foreground group-data-[state=open]:rotate-180 group-data-[state=open]:text-foreground"+ className="relative top-[1px] shrink-0 origin-center font-sans text-[10px] text-muted-foreground transition duration-300 group-hover:text-foreground group-data-[state=open]:rotate-180 group-data-[state=open]:text-foreground"aria-hidden="true">▲diff --git a/apps/web/src/content/mdx-components/aside.tsx b/apps/web/src/content/mdx-components/aside.tsxnew file mode 100644index 000000000..a0bb76952--- /dev/null+++ b/apps/web/src/content/mdx-components/aside.tsx@@ -0,0 +1,56 @@+import { cn } from "@/lib/utils";+import { cva } from "class-variance-authority";+import type React from "react";++type AsideType = "note" | "tip" | "caution" | "danger";++const ASIDE_LABEL: Record<AsideType, string> = {+ note: "Note",+ tip: "Tip",+ caution: "Caution",+ danger: "Danger",+};++const asideVariants = cva("my-4 border border-border p-4", {+ variants: {+ type: {+ note: "border-border",+ tip: "border-info",+ caution: "border-warning",+ danger: "border-destructive",+ },+ },+});++const asideTextVariants = cva("!mt-0 font-medium", {+ variants: {+ type: {+ note: "text-foreground",+ tip: "text-info",+ caution: "text-warning",+ danger: "text-destructive",+ },+ },+});++export function Aside({+ type = "note",+ title,+ children,+}: {+ type?: AsideType;+ title?: string;+ children: React.ReactNode;+}) {+ return (+ <div+ className={cn(asideVariants({ type }), "[&>*:last-child]:!mb-0")}+ role="note"+ >+ <p className={asideTextVariants({ type })}>+ {title ?? ASIDE_LABEL[type]}+ </p>+ {children}+ </div>+ );+}diff --git a/apps/web/src/content/mdx-components/card.tsx b/apps/web/src/content/mdx-components/card.tsxnew file mode 100644index 000000000..e816d6e62--- /dev/null+++ b/apps/web/src/content/mdx-components/card.tsx@@ -0,0 +1,53 @@+import { cn } from "@/lib/utils";+import Link from "next/link";+import type React from "react";++export function CardGrid({ children }: { children: React.ReactNode }) {+ return <div className="my-4 grid gap-4 sm:grid-cols-2">{children}</div>;+}++export function Card({+ title,+ children,+}: {+ title?: string;+ children: React.ReactNode;+}) {+ return (+ <div className="[&>*:last-child]:!mb-0 border border-border p-4">+ {title ? (+ <p className="!mt-0 mb-2 font-medium text-foreground">{title}</p>+ ) : null}+ {children}+ </div>+ );+}++export function LinkCard({+ title,+ href,+ description,+}: {+ title: string;+ href: string;+ description?: string;+}) {+ const isExternal = href.startsWith("http");+ return (+ <Link+ href={href}+ target={isExternal ? "_blank" : undefined}+ rel={isExternal ? "noopener noreferrer" : undefined}+ className={cn(+ "no-underline! my-4 block border border-border p-4 hover:bg-muted",+ )}+ >+ <span className="block font-medium text-foreground">{title}</span>+ {description ? (+ <span className="mt-1 block text-muted-foreground text-sm">+ {description}+ </span>+ ) : null}+ </Link>+ );+}diff --git a/apps/web/src/content/mdx-components/index.tsx b/apps/web/src/content/mdx-components/index.tsxindex 9def4b8c9..3dc62082f 100644--- a/apps/web/src/content/mdx-components/index.tsx+++ b/apps/web/src/content/mdx-components/index.tsx@@ -1,6 +1,8 @@import { Suspense } from "react";import { LatencyChartTable } from "../latency-chart-table";+import { Aside } from "./aside";import { ButtonLink } from "./button-link";+import { Card, CardGrid, LinkCard } from "./card";import { Code } from "./code";import { CustomImage } from "./custom-image";import { CustomLink } from "./custom-link";@@ -12,6 +14,7 @@ import { PricingTabs } from "./pricing-tabs";import { MDXStatusPageExample } from "./status-page-example";import { Subtle } from "./subtle";import { Table } from "./table";+import { ShowcaseYouTube } from "./youtube";export { slugify } from "./heading";@@ -29,6 +32,11 @@ export const components = {pre: Pre,table: Table,Grid,+ Aside,+ Card,+ CardGrid,+ LinkCard,+ ShowcaseYouTube,Details, // Capital D for JSX usage with propsdetails: Details, // lowercase for HTML tag replacementSimpleChart: LatencyChartTable,diff --git a/apps/web/src/content/mdx-components/youtube.tsx b/apps/web/src/content/mdx-components/youtube.tsxnew file mode 100644index 000000000..b752e8814--- /dev/null+++ b/apps/web/src/content/mdx-components/youtube.tsx@@ -0,0 +1,38 @@+function toEmbedUrl(href: string): string {+ try {+ const url = new URL(href);+ if (url.pathname.startsWith("/embed/")) return href;+ const id =+ url.searchParams.get("v") ??+ (url.hostname === "youtu.be" ? url.pathname.slice(1) : null);+ return id ? `https://www.youtube.com/embed/${id}` : href;+ } catch {+ return href;+ }+}++export function ShowcaseYouTube({+ entries,+}: {+ entries: { href: string; title?: string }[];+}) {+ return (+ <div className="my-4 grid gap-4 sm:grid-cols-2">+ {entries.map((entry, i) => (+ <div+ key={`${entry.href}-${i}`}+ className="relative aspect-video w-full overflow-hidden border border-border"+ >+ <iframe+ src={toEmbedUrl(entry.href)}+ title={entry.title ?? "YouTube video"}+ allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"+ loading="lazy"+ allowFullScreen+ className="absolute inset-0 h-full w-full"+ />+ </div>+ ))}+ </div>+ );+}diff --git a/apps/web/src/content/pages/blog/a-year-of-openstatus-may-2026.mdx b/apps/web/src/content/pages/blog/a-year-of-openstatus-may-2026.mdxindex 61fbe0fb5..4d7ee26fd 100644--- a/apps/web/src/content/pages/blog/a-year-of-openstatus-may-2026.mdx+++ b/apps/web/src/content/pages/blog/a-year-of-openstatus-may-2026.mdx@@ -15,15 +15,11 @@ This post is a year's receipt. What we shipped between then and now, what we kilSpoiler from the original Reality Check still applies: *it's been hard, really hard.*-----## The story in one paragraph12 months ago we partnered with [Emily Omier](https://www.emilyomier.com) to grill us on positioning. We killed the *ideas* of RUM, on-call, and incident management (we never actually shipped them, they just took up space in our heads), dropped synthetic-monitoring-as-headline, partnered with [Alex](https://www.linkedin.com/in/alexszczurek/) on design, [rebuilt the dashboard](/blog/new-dashboard-we-are-so-back), [rebuilt the status page](/blog/introducing-status-page-theme-explorer), doubled down on MDX-driven SEO, decoupled our monorepo, [migrated our entire API to ConnectRPC](/blog/migrating-from-zod-openapi-to-connectrpc), and went deep on AI ([skills repo](https://github.com/openstatusHQ/skills), MCP server, [CLI](/blog/building-cli-for-human-and-agents), [chat assistant](/blog/from-clickops-to-chatops), [Slack agent](/blog/openstatus-slack-agent)). In March 2026 we brought in [Shane O'Connor](https://www.linkedin.com/in/devtoolgtm/) to help us on distribution. We started posting on LinkedIn for real, stood up a subreddit, automated LinkedIn connections to widen our network reach, rechecked our ICP, and updated the homepage hero around compliance. We also welcomed Colin, our first intern, finally not a two-person team. And the community on Slack and Discord became one of our favourite parts of the work. Today: focused product, ~1M Google impressions in the last 3 months, a real distribution motion, a defensible wedge. This is the honest version of how we got here, including what didn't work.-----## Section 1: Where we wereMarch 2025. We didn't feel particularly unique. We were chasing stars instead of talking to the people actually using the product. We were lost.@@ -32,8 +28,6 @@ For a visual receipt: [v1.openstatus.dev](https://v1.openstatus.dev). The old siToday, May 2026: same product category, same two founders, plus [Colin](https://www.linkedin.com/in/colin-ozanne/), our first intern. Different company underneath. There's one chart that frames the whole year, but we've saved it for the numbers section, where it belongs.-----## Section 2: The shiftThe mental-model change, in two parts.@@ -62,8 +56,6 @@ The mental-model change, in two parts.**The line:** *We thought our problem was technical. It was strategic. We needed someone outside the team to ask the questions we were avoiding.* Emily named the product. Alex shaped the look. Shane named the distribution problem we'd been dodging.-----## Section 3: The pillars**The funnel frame.** This is the spine. It came out of the year-in-review post, and it explains the chart.@@ -255,8 +247,6 @@ Dashboard for clickers, chat for talkers, Terraform for committers. Same `servic**The honest line:** *We're not adding AI to look modern. We're using it because the actual workflow demands it. Status pages are a place where "don't make me leave my terminal" is the whole product.*-----## Section 4: The outbound motion (added March 2026)The pillars above are the *inbound* funnel: how strangers find us. By Q1 2026 it was clear we'd built a system that pulled people in but didn't reach out to anyone. As devs, we'd rather ship than DM. Shane changed that, not by handing us a full GTM operation, but by getting us to actually show up.@@ -281,8 +271,6 @@ This is the newest part of the story (~2 months old at time of writing). Too earTwo months is too short for a verdict. The fact that we're showing up for the work at all is the change.-----## Section 5: A few numbers for comparisonWe're wary of bragging with numbers we made up ourselves. So we lean on the ones we don't control: GitHub stars, Google Search Console impressions, follower counts pulled straight from each platform. Not perfect, but at least nobody at openstatus gets to put a thumb on the scale.@@ -320,8 +308,6 @@ Here they are, before and after.- **Product Hunt, October 2025.** [Flo Merian](https://x.com/fmerian) launched us *with us getting surprised* on a Saturday. We finished #2 of the day, behind Anthropic Skills. The conversion to actual users was effectively zero, and we didn't even make the newsletter. We wrote the whole thing up in [*Our Product Hunt Launch: The Brutal Reality*](/blog/our-producthunt-launch-brutal-reality). *Lesson: Product Hunt isn't a marketing strategy in 2026.* Also, sometimes the YOLO is fine.- **The first openstatus retreat:** Kochel am See, Bavarian beer, e-bikes, Kaiserschmarrn. It's also where we wrote the [2026 roadmap](/blog/2026-roadmap) together. Two-person team doesn't mean two people in two cities forever.-----## Section 6: LessonsThe actual learnings, year over year. Some of these are old hats; the value is in the receipts now.@@ -392,8 +378,6 @@ We assumed users came for monitoring. They came for the status page and stayed fFor *years* our headline was some flavour of "open-source uptime monitoring and status page." Even [v1.openstatus.dev](https://v1.openstatus.dev) was an iteration of that ("Showcase your uptime with a status page"). All true, all accurate, all aimed at the developer who was already going to like us. The new hero leads with the compliance story, because that's the question on the other side of the developer's desk. The dev still adopts the tool, but the headline needs to also answer the question their team lead is being asked. Write to *that* reader.-----## Closing thoughtSteal from the [Reality Check post](/blog/product-strategy-a-reality-check):diff --git a/apps/web/src/content/pages/blog/deploy-private-locations-raspberry-pi.mdx b/apps/web/src/content/pages/blog/deploy-private-locations-raspberry-pi.mdxindex c67066a29..d5f5fab3a 100644--- a/apps/web/src/content/pages/blog/deploy-private-locations-raspberry-pi.mdx+++ b/apps/web/src/content/pages/blog/deploy-private-locations-raspberry-pi.mdx@@ -18,8 +18,6 @@ Time to revive it!alt="My bare metal Raspberry Pi on top of the receiver I use for AirPlay"/>-----## Deployment GuideObviously connecting to the Raspberry Pi via `ssh` - and if you're like me, the default password is secure enough:@@ -182,8 +180,6 @@ It’s useful for:- Testing network latency from real-world locations (like your office or home)- Running low-cost monitoring nodes on tiny devices (e.g. in agriculture or industrial setups)-----## Closing ThoughtsAnd that’s it - my **Raspberry Pi (2016)** is officially back in action. Running quietly next to my receiver, it’s now part of the openstatus network, checking endpoints from my home.diff --git a/apps/web/src/content/pages/blog/migrating-from-zod-openapi-to-connectrpc.mdx b/apps/web/src/content/pages/blog/migrating-from-zod-openapi-to-connectrpc.mdxindex d82e7b63f..c77f48a58 100644--- a/apps/web/src/content/pages/blog/migrating-from-zod-openapi-to-connectrpc.mdx+++ b/apps/web/src/content/pages/blog/migrating-from-zod-openapi-to-connectrpc.mdx@@ -9,8 +9,6 @@ category: "engineering"**TL;DR:** Two APIs. Double the bugs. Double the work. We maintain tRPC for ourselves and REST for everyone else. We're unifying them with ConnectRPC—a schema-first API that's type-safe *and* curl-able. Here's how we're doing it, and how AI is accelerating the migration.-----## The Problem: Two APIs, Double the WorkHere's a confession: we weren't dogfooding our own public API.@@ -26,8 +24,6 @@ This debt compounds. We needed to merge them—but we didn't want to sacrifice tThe answer wasn't REST. It wasn't GraphQL. It was **ConnectRPC**.-----## Why ConnectRPC WonWe evaluated several options. ConnectRPC stood out because it bridges strict contracts with developer ease.@@ -160,8 +156,6 @@ This matters even more now that AI agents are consuming APIs. They work better w-----## How We Built It: Hono + ConnectRPCOur API runs on **Hono**. Here's the integration:@@ -317,8 +311,6 @@ export function authInterceptor(): Interceptor {For validation, we use `@connectrpc/validate` which runs protovalidate constraints automatically. See the full implementation in [our repo](https://github.com/openstatushq/openstatus/tree/main/apps/server/src/routes/rpc).-----## Before and After: Validation Moves to the Schema**Before (zod-openapi):** Validation defined in TypeScript, separate from the OpenAPI spec.@@ -390,8 +382,6 @@ async createHTTPMonitor(req, ctx) {The difference: validation constraints live in the proto schema and execute at runtime via protovalidate.-----## The Payoff: Auto-Generated Hooks with Full Type InferenceWith `@connectrpc/connect-query`, we get TanStack Query hooks generated from the proto schema:@@ -453,8 +443,6 @@ export default async function MonitorsPage() {Full type safety. Auto-generated hooks. The same API your users consume.-----## How AI Helped Us Ship FasterIn early 2026, we treated this migration as a test case for AI-assisted development.@@ -470,8 +458,6 @@ The result? **AI is exceptionally good at schema work.**We shifted from "writing boilerplate" to "reviewing code." What we estimated at months is now tracking to finish in weeks.-----## Testing: Just HTTPNo special test setup. ConnectRPC endpoints are plain HTTP:@@ -509,8 +495,6 @@ describe("MonitorService", () => {});```-----## What's NextTwo things:diff --git a/apps/web/src/content/pages/blog/nobody-should-hand-code-a-data-table.mdx b/apps/web/src/content/pages/blog/nobody-should-hand-code-a-data-table.mdxindex 538a0846d..404263687 100644--- a/apps/web/src/content/pages/blog/nobody-should-hand-code-a-data-table.mdx+++ b/apps/web/src/content/pages/blog/nobody-should-hand-code-a-data-table.mdx@@ -21,8 +21,6 @@ We rebuilt the entire developer experience — refactoring code, improving compo<Image src="/assets/posts/nobody-should-hand-code-a-data-table/data-table-filters-homepage.png" alt="The data-table-filters homepage." />-----## State management adaptersBefore, the table was married to [nuqs](https://nuqs.dev?referrer=openstatus) (URL search params). If you didn't want URL state, tough luck.diff --git a/apps/web/src/content/pages/blog/telegram-group-qr-integration.mdx b/apps/web/src/content/pages/blog/telegram-group-qr-integration.mdxindex a8edaf1f6..24ec71093 100644--- a/apps/web/src/content/pages/blog/telegram-group-qr-integration.mdx+++ b/apps/web/src/content/pages/blog/telegram-group-qr-integration.mdx@@ -13,8 +13,6 @@ We didn't do that.This post explains the two-phase QR code flow we built to connect Telegram groups to OpenStatus — and why the approach we took is more reliable, simpler to deploy, and doesn't require us to maintain a live webhook endpoint at all.-----## The Problem with WebhooksWebhooks are powerful, but they come with operational overhead that can exceed the complexity of a one-time setup flow:@@ -28,8 +26,6 @@ For our use case — a one-time group connection during initial setup — this fThe alternative? Telegram's `getUpdates` long-polling API. It's the simpler sibling of webhooks, designed for bots that pull updates on demand rather than receive them pushed. We already had the infrastructure: a working API, Redis, and a frontend capable of polling. So we leaned in.-----## The Two-Phase FlowThe core challenge with Telegram group notifications is that **you can't directly obtain a group chat ID from a user**. Unlike a "Log in with Telegram" flow, groups don't have a built-in sign-in mechanism. The user can't just authenticate and grant group access.@@ -49,8 +45,6 @@ Now that we know *who* initiated the flow (via their private `chatId`), we waitOnce both phases complete, we have the group's `chatId` — which is what gets stored and used for alert delivery.-----## Token Management: One Key per WorkspaceDuring Phase 1, we need to issue a short-lived, single-use token that links a QR scan back to a specific OpenStatus workspace.@@ -82,8 +76,6 @@ if (storedToken && receivedToken === storedToken) {This approach scales horizontally: adding new workspaces requires no coordination between API instances, since each one can independently manage its own Redis keys.-----## Stale Update Prevention: Timestamp FilteringHere's the subtle problem with `getUpdates`: **Telegram's API returns updates from the last 24 hours by default**. If a user previously added the bot to a group (even accidentally), that event would still be in the update feed.@@ -104,8 +96,6 @@ This also cleanly handles the **reset flow**. If a user accidentally adds the boThe beauty of this approach: **the client drives the filtering logic**, and the server is just a passive validator. No state needs to be stored on the backend beyond the 30-minute token.-----## Ownership Verification in Phase 2Detecting that the bot was added to a group is straightforward. But we need to make sure *the right user* did it. Otherwise, any user who scans the QR could add the bot to an arbitrary group that doesn't belong to them.@@ -138,8 +128,6 @@ function extractGroupBotAddition(update, privateChatId, botUsername) {All three Telegram field variants (`new_chat_participant`, `new_chat_member`, `new_chat_members`) are checked because the field name varies across bot API versions and group types. It's defensive, but necessary — we've learned that Telegram's API isn't always consistent across versions and group configurations.-----## Frontend State: A Reducer-Driven FlowManaging the two-phase flow on the client required careful state handling. We used `useReducer` to model the flow explicitly, treating the entire QR connection process as a state machine.@@ -179,8 +167,6 @@ const { data: updates } = useQuery({Polling automatically stops once `chatId` is set in the form — there's no manual cleanup needed. The `enabled` flag handles it reactively. This means the frontend naturally stops polling once the connection succeeds, freeing up resources without explicit teardown logic.-----## Why This Architecture ScalesThe thing that makes this design hold up at scale is that **the server stays stateless between polls**.@@ -199,8 +185,6 @@ Redis handles token TTL and single-use deletion atomically. The frontend managesAdding a new workspace doesn't change anything server-side. The Redis key pattern `telegram:workspace_token:${workspaceId}` scales horizontally with zero coordination between instances. If you double your API servers, the system just works.-----## The User ExperienceFrom a user's perspective, the flow is straightforward:@@ -215,8 +199,6 @@ From a user's perspective, the flow is straightforward:No webhooks. No manual token copying. No server-side secrets exposed in URLs. No stale data from leftover `getUpdates` history. The setup takes about 10 seconds.-----## Key TakeawaysThis pattern works well when:diff --git a/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx b/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdxnew file mode 100644index 000000000..3271e9373--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx@@ -0,0 +1,129 @@+---+category: Concepts+title: Building Trust with Status Pages+description: "Understanding how to communicate effectively during incidents and build user trust through transparency."+---+++```++------------------------------------------------++| openstatus Status Page |++------------------------------------------------++| Service Name | Status | Uptime |++-------------------+--------+-------------------++| Web Server | ✅ OK | 99.9% |+| Database | ✅ OK | 99.8% |+| API Gateway | ⚠️ Degraded | 99.5% |+| Monitoring | ✅ OK | 100% |+| Payment Processing| ✅ OK | 99.7% |++-------------------+--------+-------------------++| Incidents: |+| |+| - Degraded performance on API Gateway due |+| to high traffic. Our team is investigating.|++------------------------------------------------++```++## The purpose of a status page++A status page is more than just a dashboard of green lights. It's a critical tool for communication and a cornerstone of building trust with your users. Its primary purpose is to provide a single, authoritative source of truth about your service's health and any ongoing incidents.++When done right, a status page:+- **Reduces support burden**: Users can self-serve information about outages instead of contacting your team.+- **Builds trust**: Proactive transparency, even when things go wrong, demonstrates accountability.+- **Improves communication**: It provides a central and consistent channel for incident updates.+- **Demonstrates professionalism**: It shows that you take reliability and user experience seriously.++This article explores the principles that make a status page an effective tool for building trust.++## Principles of Effective Status Pages++### Maintain Transparency and Honesty++A status page's effectiveness hinges on being a reliable source of truth. Be upfront about issues, even minor ones. Hiding problems erodes user trust and can lead to frustration and a higher support load.++- **Communicate Clearly:** Use simple, non-technical language. Your users shouldn't need a technical dictionary to understand the impact of an issue.++- **Be Timely:** Update the page as soon as an incident is confirmed. Provide regular, predictable updates throughout the resolution process, even if the only update is "we're still working on it."++### Automate Where Possible++Manual updates during a high-stress outage are prone to error and can be slow. Automation ensures that your status page reflects reality quickly and accurately.++- **Integrate Monitoring Tools:** Your status page should be directly connected to your internal monitoring and alerting systems. When a metric crosses a threshold (e.g., a high error rate), the status page can be updated automatically to reflect a degraded state.++- **Use an API:** We provide APIs that allow you to programmatically update component statuses and post new incidents, integrating your status page into your incident response workflows.+++### Provide Context-Rich Incident Communication++When an incident occurs, a structured narrative helps users understand the situation.++- **Start with the Impact:** Clearly and concisely state what the problem is from the user's perspective. For example, "Users are currently unable to log in."++- **Explain the Cause (When Known):** Briefly explain the root cause if you've identified it. Transparency here is key.++- **Outline Next Steps and ETA:** Explain what is being done to resolve the issue and provide an estimated time to resolution if possible. It's better to give a conservative estimate or no estimate than to give one you can't meet.++A typical incident communication lifecycle looks like this:++- **Investigating:** "We're currently investigating an issue affecting user logins."++- **Identified:** "We've identified the root cause as a database connection issue and are working on a fix."++- **Monitoring:** "A fix has been deployed, and we're monitoring the system to ensure stability."++- **Resolved:** "The issue has been resolved. We will publish a post-mortem within 48 hours."+++### Ensure Easy Accessibility++Your status page is useless if no one can find it.++- **Prominent Link:** Link to your status page from your application's footer, your main website, and your support documentation.++- **Custom Domain:** Use a simple, memorable URL like `status.yourcompany.com`.++## Advanced Considerations for Deeper Trust++### Scheduled Maintenance++Communicating planned downtime is just as important as communicating unexpected incidents.+- Announce maintenance well in advance (e.g., at least 72 hours).+- Display upcoming maintenance windows clearly on the status page.+- Send reminders to subscribers before maintenance begins.++### Historical Data and Post-Mortems++Demonstrate your commitment to reliability by being open about your track record.+- Display historical uptime percentages (e.g., over the last 30/60/90 days).+- Link to past incidents and their post-mortems. Being honest about past failures and what you've learned from them is a powerful trust-builder.++### Subscriber Notifications++Allow users to opt-in to the level of communication they want.+- Email notifications for new incidents and resolutions.+- SMS for critical alerts (if applicable).+- RSS/Atom feeds for users who want to integrate your status into their own monitoring.++## Common Pitfalls to Avoid++1. **Claiming unrealistic uptime**: Don't claim 100% uptime unless you can back it up. Honesty is better than perfection.+2. **Hiding or downplaying incidents**: Users will find out anyway. It's better they hear it from you.+3. **Using technical jargon**: Write for a broad audience, not just other engineers.+4. **Leaving users in the dark**: During an incident, regular updates are crucial, even if there's no new information. A simple "still investigating" is better than silence.+5. **Hosting your status page on the same infrastructure**: Your status page must be available even when your main service is down.++## Implementing with openstatus++openstatus is designed to make implementing these principles straightforward:++- **[Create a status page](/docs/tutorial/how-to-create-status-page)** - Get set up in minutes.+- **[Configure your page](/docs/tutorial/how-to-configure-status-page)** - Customize its appearance to match your brand.+- **[Understand uptime calculations](/docs/concept/uptime-calculation-and-values)** - Be transparent about how you measure uptime.++## Next steps+++- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** - Learn more about monitoring what you communicate.+- **[Status page reference](/docs/reference/status-page)** - Dive into technical configuration options.diff --git a/apps/web/src/content/pages/docs/concept/getting-started.mdx b/apps/web/src/content/pages/docs/concept/getting-started.mdxnew file mode 100644index 000000000..45b6be274--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/getting-started.mdx@@ -0,0 +1,30 @@+---+title: Foundational Concepts+description: "Understand uptime monitoring, latency vs response time, SLA calculations, and the design decisions behind openstatus."+category: Concepts+---++## Building a solid foundation++This section of our documentation is dedicated to explanation. It's not about quick fixes or step-by-step instructions. Instead, it's here to help you build a deep understanding of uptime monitoring and the principles behind openstatus.++A solid mental model will empower you to use our tools more effectively, make better decisions for your own systems, and communicate with your team and stakeholders with clarity and confidence.++We'll explore the "why" behind the "what," covering core concepts, best practices, and the design philosophy that guides our development.++### Core Concepts++Start here to grasp the fundamental building blocks of uptime monitoring.++- **[Uptime Monitoring](/docs/concept/uptime-monitoring)**: What is it, why does it matter, and how does it work?+- **[Uptime Calculation and Values](/docs/concept/uptime-calculation-and-values)**: A look under the hood at how uptime percentages are calculated and what they truly represent.+- **[Latency vs Response Time](/docs/concept/latency-vs-response-time)**: Untangle the difference between these two critical performance metrics.++### Best Practices & Philosophy++Learn from experience and understand our approach to modern monitoring.++- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)**: How to communicate effectively during incidents and maintain user trust.+- **[Uptime Monitoring as Code](/docs/concept/uptime-monitoring-as-code)**: The why and how of managing your monitoring configuration in a GitOps workflow.++Have questions or want to discuss these concepts? [Join our community](/docs/help/support) and share your thoughts!diff --git a/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx b/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdxnew file mode 100644index 000000000..81836a50c--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx@@ -0,0 +1,126 @@+---+category: Concepts+title: Understanding Latency vs Response Time+description: "Deep dive into the difference between latency and response time, and why both matter for monitoring"+---++## The confusion++Latency and response time are often used interchangeably, but they measure different things. Understanding the distinction is crucial for effective monitoring and performance optimization.++**The key difference:**+- **Latency** measures network travel time+- **Response time** measures total time including server processing++Both metrics matter, but for different reasons.++## What is latency?++Latency and response time are two different metrics used in uptime monitoring. Latency measures the time it takes for a request to travel from the probes to the server and back. Response time is the time it takes for the server to process the request and send back a response, plus the latency.++```+openstatus Network Server (Website)+ | | |+ |------- Request ---------->| |+ | (Timestamp A: Send) | |+ | |------- Process --------->|+ | | (Server processing time) |+ | |<------- Response --------|+ | | (Timestamp B: Receive) |+ | | |+Latency = Timestamp B - Timestamp A+```++Latency is the time it takes for data to travel from its source to its destination. Think of it as the round-trip time (RTT) for a network packet. This delay is influenced by several factors:++- **Distance:** The physical distance between the client and the server. Data traveling across continents will have higher latency than data traveling within the same city.++- **Network Congestion:** When too much data is on the network, it can slow down transmission, similar to a traffic jam on a highway.++To measure latency, you can monitor endpoints like `/ping` or `/healthcheck` with minimum server processing time.++## What Is Response Time?++```+ openstatus Network Server+ | | |+(Start) |------- Request -------->| |+(T1) | | |+ | |--- Processing ----->|+ | | (Server's work) |+ | |<-- Response Data ---|+ | | |+(End) |<--- (Received) ---------| |+(T2) | | |++ Response Time = T2 - T1+```+++Response time is the total time from the moment a user's request is sent until the moment the first byte of the server's response is received. It includes both the network latency and the server's processing time.++Response time = Network Latency + Server Processing Time++The server processing time is the duration the server spends on tasks like:++- Executing database queries.+- Running application logic.+- Generating the HTML or JSON response.++A high response time often indicates a problem with the server-side application itself. For example, slow database queries or inefficient can dramatically increase the response time, even if the network latency is low.+++## Why the distinction matters for uptime monitoring++Understanding the difference between these two metrics is crucial for diagnosing performance issues.++- If your monitoring shows a **high response time but low latency**, the problem is likely with your server's performance. You should investigate your application's code, database queries, and server resources.++- If both your **latency and response time** are high, the issue is likely network-related. This could be due to a poor connection between the monitoring location and your server, or a broader network issue.++- **Response time is the ultimate measure of user experience** because it reflects the full journey of a request. Users don't just care how fast a packet can get to the server; they care how long it takes to see the results.++By monitoring both metrics, you can quickly pinpoint whether a performance slowdown is caused by your application or by the network.++## Practical implications++### For monitoring strategy++- **Monitor both metrics**: Don't rely on just one+- **Set appropriate thresholds**: Latency thresholds should be lower than response time thresholds+- **Consider geographic factors**: Latency varies by monitoring location+- **Track trends**: Sudden changes in either metric indicate issues++### For optimization++- **Reduce latency**: Use CDNs, optimize routing, choose closer hosting+- **Improve response time**: Optimize code, database queries, caching+- **User location matters**: Users far from your server will always see higher latency++### Common scenarios++**Scenario 1: Consistent latency, variable response time**+- Indicates server-side performance issues+- Look at: Database queries, API calls, resource utilization++**Scenario 2: High latency from specific regions**+- Indicates geographic network issues+- Solution: Add regional monitoring points or CDN++**Scenario 3: Both metrics degrading**+- Could be network saturation or DDoS attack+- Check: Network bandwidth, traffic patterns, security++## What openstatus tracks++openstatus monitors and displays:+- **Total response time**: The complete user experience+- **Detailed timing breakdown**: DNS, TCP, TLS, request, response+- **Regional differences**: Compare performance across locations+- **Historical trends**: Identify patterns over time++## Next steps++- **[Create your first monitor](/docs/tutorial/how-to-create-monitor)** - Start tracking these metrics+- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** - Broader monitoring concepts+- **[HTTP monitor reference](/docs/reference/http-monitor)** - Technical specificationsdiff --git a/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdxnew file mode 100644index 000000000..29a028c37--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx@@ -0,0 +1,78 @@+---+category: Concepts+title: Uptime Calculation and Shared Values+description: Understand how openstatus calculates uptime — absolute (duration or requests) and manual modes — and choose which values to share on your status page.+---++Let’s face it - uptime values can be a complete lie if they’re not properly connected to monitoring.++We want to make uptime transparent and configurable. You decide how your uptime is calculated and which values you want to share on your status page.+When monitoring an endpoint, a check can end up in one of three states:++- ✅ Success – everything’s fine+- ⚠️ Degraded – slow or partially failing+- ❌ Down – no response or full failure++We now offer multiple types of uptime calculation:+- **Absolute** (default): derived directly from your monitoring data+ - **Duration**: aggregated from the incidents duration+ - **Requests** (default): aggregated from the request values+- **Manual**: for teams that prefer full control over what’s shown++**TL;DR**++| Type | Source of Truth | What Users See | Best For |+|-------------|----------------------|-------------------------------------|----------------------------------|+| **Duration** (Absolute) | Incident duration | Time based uptime, proportional colors | Accurate long-term view |+| **Request** (Absolute) | Every ping result | Request-based uptime % | Real-time reflection |+| **Manual** | Manually set status | Controlled, narrative updates | Transparency without monitoring |++<br />++Let’s break them down!++## Absolute Type++The absolute type calculates uptime based on actual monitoring results. It’s the most accurate reflection of what’s really happening, and comes in two variants: _Duration_ and _Request_.+Both of these share real data with your users - incidents, degraded states, and historical uptime - but they differ in how they aggregate and display that data.++---++### Duration++The duration value is calculated from the **total monitoring time and the duration of incidents**.++In simple terms: `uptime = (total time - incident duration) / total time`++This means uptime is based on how long something was down, not how many checks failed. Only incident durations are included in the calculation.++Temporary single-region ping failures (e.g., one location failing once, sometimes this just happens) are not propagated to users - because these often don’t represent a real outage. That’s also why we recommend at least three locations per monitor for redundancy.++The proportional colors in the status bar are drawn from these duration values. Hovering over a day shows both incidents and status reports, so users can explore what happened.++---++### Request++The request value is more straightforward - it looks at each ping result individually. **Every check we run contributes to your uptime score**.++In simple terms: `uptime = (success + degraded) / total requests`++This is the current default mode for most openstatus users. It’s simple, data-driven, and updates immediately as new results come in.++Like with duration, hover cards display incidents and status reports, giving your users a quick overview of recent events.++## Manual Type++The manual type is for teams who want to **fully control what’s shown** on your status page, without relying on automatic checks.+By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes - independent of any monitoring data.++This is ideal if:+- you don’t have synthetic monitoring set up yet,+- or you’re sharing updates that aren’t tied to uptime (e.g., service degradation due to external dependencies).++In this mode, all displayed uptime values and statuses come from your shared report data, not from active pings.++In simple terms: `uptime = (total duration - status report duration) / total duration`++> **Note**: the values you are defining are attached to a status page. You cannot change them per monitor (for now).diff --git a/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx b/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdxnew file mode 100644index 000000000..90c390f2a--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx@@ -0,0 +1,125 @@+---+category: Concepts+title: Understanding Monitoring as Code+description: "Why and how to manage monitoring configuration as code for GitOps workflows"+---++## The traditional approach (and its problems)++Traditionally, monitoring is configured through web dashboards:+1. Log into a web interface+2. Click through forms to create monitors+3. Manually replicate configuration across environments+4. No audit trail of who changed what+5. Difficult to review changes before they go live++This works for small teams with few monitors, but doesn't scale.++## What is monitoring as code?++**Monitoring as Code** treats your monitoring configuration the same way you treat your application code: as text files that can be versioned, reviewed, and deployed through automated pipelines.++Instead of clicking buttons, you define monitors in YAML:++Uptime monitoring is a vital part of any robust system, ensuring your services are online and available to users. Historically, this has involved manually configuring monitors through a web interface, which can be tedious and prone to human error. Uptime Monitoring as Code changes this by treating your monitoring configurations like any other part of your application-as code.+++## Why Use Uptime Monitoring as Code?++This approach offers significant advantages:++- **Version Control:** By defining your monitors in a YAML file, you can track every change, rollback to previous versions, and see who made which modifications using tools like Git. This is crucial for auditing and troubleshooting.++- **Automation and Consistency:** Your monitoring setup can be part of your automated deployment pipeline. When you deploy a new service, its monitors are created automatically, ensuring consistency across your entire infrastructure. This eliminates the risk of forgetting to set up monitoring for a new service.++- **Collaboration:** A code-based approach simplifies collaboration among teams. A developer can create a new monitor definition in the YAML file and submit it for peer review, just as they would with any other code change. This promotes a shared understanding of your system's health.++- **Scalability:** Manually setting up hundreds of monitors is a nightmare. With a code-based approach, you can programmatically generate configurations for a large number of services, making it easy to scale your monitoring as your infrastructure grows.++- **Simplified Auditing:** Since the entire configuration is in a file, it's easy to see the current state of your monitors at a glance. You don't have to navigate through multiple screens in a web UI.+++## How It Works with openstatus++ We offer the use ofa simple, human-readable YAML file to define all uptime monitors. This file serves as the single source of truth for your monitoring setup. You define each monitor with its URL, expected status code, and other parameters.++Here’s an example of what your `openstatus.yaml` file might look like:++```yaml+# openstatus.yaml+# yaml-language-server: $schema=https://www.openstatus.dev/schema.json+uptime-monitor:+ name: "Uptime Monitor"+ description: "Uptime monitoring example"+ frequency: "10m"+ active: true+ regions:+ - iad+ - ams+ - syd+ - jnb+ - gru+ retry: 3+ kind: http+ request:+ url: https://openstat.us+ method: GET+ headers:+ User-Agent: openstatus+ assertions:+ - kind: statusCode+ compare: eq+ target: 200++graphql-monitor:+ name: "Graphql"+ description: "GitHub GraphQL API"+ frequency: "10m"+ active: true+ regions:+ - iad+ - ams+ - syd+ - jnb+ - gru+ retry: 3+ kind: http+ request:+ url: https://api.github.com/graphql+ method: POST+ headers:+ User-Agent: openstatus+ Authorization: Bearer YOUR_TOKEN_HERE+ body: |+ {+ "query": "query { viewer { login }}"+ }+```++### Making Changes with the CLI++Once your `openstatus.yaml` file is ready, you use our [command-line interface (CLI)](/docs/tutorial/get-started-with-openstatus-cli) to apply the changes. The CLI compares your local configuration with the current state of your monitors and applies only the necessary changes creating new monitors, updating existing ones, or deleting those no longer defined.++**Common CLI Commands:**++- `openstatus monitors apply`: Applies the changes defined in your `openstatus.yaml` file.+- `openstatus monitors import`: Import the monitors from your dashboard to a new `openstatus.yaml` file.++By integrating this **Uptime Monitoring as Code** workflow into your development lifecycle, you can achieve a more reliable, consistent, and scalable system. It's about moving from manual clicks to automated, version-controlled operations.++## Best practices++1. **Start simple**: Begin with a few monitors, expand as you learn+2. **Use templates**: Create reusable patterns for common monitor types+3. **Environment variables**: Use secrets management for tokens and sensitive data+4. **Review changes**: Always review diffs before applying+5. **Document decisions**: Use commit messages to explain "why"++## Next steps++Ready to implement monitoring as code?++- **[Get Started with CLI](/docs/tutorial/get-started-with-openstatus-cli)** - Install and configure the CLI+- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Real-world example+- **[CLI Reference](/docs/reference/cli-reference)** - Complete command documentation+- **[YAML Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurationsdiff --git a/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx b/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdxnew file mode 100644index 000000000..cfb532086--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx@@ -0,0 +1,142 @@+---+title: Understanding Uptime Monitoring+description: A deep dive into uptime monitoring concepts, architecture, and best practices+category: Concepts+---++## What is uptime monitoring?++Uptime monitoring is the practice of continuously asking a simple question: "Is our service working correctly for our users?" It's a systematic, automated process for checking the availability, performance, and correctness of a website, server, or application.++Instead of waiting for users to report a problem, uptime monitoring acts as a proactive defense, alerting you the moment an issue arises. This helps you minimize downtime and protect your reputation.++At its core, uptime monitoring answers three critical questions:+1. **Is my service available?** Can users reach it?+2. **Is it performing well?** Are response times fast enough?+3. **Is it functioning correctly?** Is it returning the expected data and behaving as intended?+++```++----------------++| Service to be |+| Monitored |++----------------++ ▲+ |+ | (Network Latency)+ |++-----+-------+ +-----+-------+ +-----+-------++| Monitoring | | Monitoring | | Monitoring |+| Node (USA) | | Node (EU) | | Node (Asia) |++-----+-------+ +-----+-------+ +-----+-------++ | | |+ |---------------|-----------------|+ ▼ ▼ ▼++------------------------------------------------++| Global Uptime Monitoring Service |+| |+| - Sends automated requests (e.g., pings or |+| HTTP checks) from all nodes at set intervals |+| - Records response time and success/failure |+| - Compares results from different nodes |+| - If a failure or a slow response is detected, |+| it triggers an alert. |++------------------------------------------------++ |+ | (Alerts: Email, SMS, Slack, etc.) 🔔+ |++-----+-----++| Your Team |++-----------++```+++## Key Concepts++- **Downtime**: The period when a service is unavailable or not functioning as expected. It can be caused by server failures, network issues, software bugs, or even cyberattacks.++- **Uptime**: The percentage of time a service is available and operational. A high uptime percentage (e.g., 99.9% or "three nines") indicates reliability.++- **Alerting**: The system of notifying a team or individual when downtime is detected. Alerts can be sent via email, SMS, Slack, or other communication channels.++## Why Uptime Monitoring is Crucial++- **Business Continuity**: Downtime can lead to significant financial losses, damage to reputation, and loss of customer trust. Uptime monitoring helps you address issues quickly, ensuring your services are always available to your users.++- **Performance Insight**: Monitoring tools often provide data on latency and response times, giving you insights into your service's performance beyond just availability. This can help you optimize your infrastructure and user experience.++- **Proactive Problem Solving**: Instead of waiting for a customer to report an issue, uptime monitoring allows you to be the first to know about it. This enables you to troubleshoot and resolve problems before they escalate.++## How it Works++Uptime monitoring typically involves a monitoring agent that periodically sends a request (like an HTTP GET request) to your service.++- If the service responds with a successful status code (e.g., 200 OK), it's considered up.++- If the service returns an error code, a timeout, or no response, the agent will perform a re-check from a different location to confirm the outage. This helps prevent false alarms caused by temporary network glitches.++- Upon confirmation, the system triggers an alert, notifying the relevant team members. The monitoring system will continue to check the service until it's back online, at which point a recovery alert is often sent.++Common types of checks include:++- **HTTP/HTTPS checks:** Verify a website is accessible and returns a valid response.+- **TCP checks:** Confirm a server is reachable on the network.++++## Planning an Uptime Monitoring System++When planning your own uptime monitoring system, consider the following:++1. Define What to Monitor: Identify all critical services, websites, APIs, and servers that need to be monitored. Prioritize based on business impact.++2. Select a Monitoring Tool: Choose a tool that fits your needs. Options range from simple free services to complex enterprise-level platforms. Look for features like:++ - **Multiple locations:** Checks from various geographic regions to ensure global availability.++ - **Customizable alerting:** Set up different alert thresholds and notification methods.++ - **Reporting and dashboards:** Visualize uptime history, performance metrics, and incident reports.++ - **Integrations:** Connect with your existing tools like Slack, PagerDuty, or email.++3. **Establish Alerting Rules:** Determine who should be notified and when. Set up an escalation policy, for example, if a primary on-call engineer doesn't respond within 15 minutes, the alert is sent to a manager.++4. **Regularly Review and Optimize:** Monitor your monitoring system itself. Review historical data to identify recurring issues, fine-tune alert thresholds, and update your list of monitored services as your infrastructure evolves.++## The human factor++While uptime monitoring is largely automated, it's important to remember the human aspects:++- **Alert fatigue**: Too many false positives can lead teams to ignore alerts. Fine-tune your monitoring to reduce noise.+- **On-call burden**: Distribute monitoring responsibilities fairly and ensure adequate coverage.+- **Communication**: During incidents, clear communication with users is as important as technical fixes.+- **Post-mortems**: Learn from downtime by conducting blameless post-mortems.++## Monitoring philosophy++Different approaches to monitoring reflect different philosophies:++- **Optimistic monitoring**: Assume everything is working unless proven otherwise. Alert on failures.+- **Pessimistic monitoring**: Assume nothing works unless actively verified. Alert on missing data.+- **SLI/SLO based**: Monitor Service Level Indicators against defined Service Level Objectives.++openstatus supports all these approaches, letting you choose what works best for your team.++## Beyond basic availability++Modern uptime monitoring goes beyond simple "up or down" checks:++- **Performance monitoring**: Track response times and identify degradation before outages.+- **Geographic monitoring**: Verify availability from multiple regions to catch regional issues.+- **Synthetic monitoring**: Simulate user journeys to catch functional issues.+- **Real user monitoring (RUM)**: Complement synthetic checks with actual user experience data.++## Next steps++Now that you understand uptime monitoring concepts:++- **[Get started with a monitor](/docs/tutorial/how-to-create-monitor)** - Apply these concepts in practice+- **[Learn about uptime calculations](/docs/concept/uptime-calculation-and-values)** - Understand how uptime percentages work+- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** - Communicate effectively during incidents+- **[Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** - Manage monitoring configuration programmaticallydiff --git a/apps/web/src/content/pages/docs/guides/getting-started.mdx b/apps/web/src/content/pages/docs/guides/getting-started.mdxnew file mode 100644index 000000000..a597e57b6--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/getting-started.mdx@@ -0,0 +1,47 @@+---+category: Guides+title: How-to Guides+description: "Practical guides for integrating openstatus with GitHub Actions, OTLP endpoints, Cloudflare, and more."+sidebar:+ label: Guides Overview+ order: 1+---++## 🛠️ How-to Guides++### What you'll find here++Our how-to guides are designed to help you:+- Solve specific problems with step-by-step instructions+- Implement advanced features and integrations+- Customize and extend your openstatus setup++### Monitoring & Integration++Extend your monitoring capabilities:++- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Set up monitoring for Model Context Protocol servers+- **[Export Metrics to OTLP Endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** - Send monitoring data to your observability platform+- **[Run Synthetic Tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** - Automate testing in your CI/CD pipeline++### Status Pages & Widgets++Share your status with users:++- **[Add SVG Status Badge to GitHub README](/docs/guides/how-to-add-svg-status-badge)** - Display real-time status in your repository+- **[Use React Status Widget](/docs/guides/how-to-use-react-widget)** - Embed live status updates in your React application+- **[Deploy Status Page on Cloudflare Pages](/docs/guides/how-deploy-status-page-cf-pages)** - Host your status page on Cloudflare's edge network++### Infrastructure & Deployment++Self-host and customize your setup:++- **[Deploy Private Locations on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - Run monitoring agents in your own infrastructure+- **[Self-Host openstatus](/docs/guides/self-hosting-openstatus)** - Deploy openstatus on your own servers+- **[Self-Host Status Page Only](/docs/guides/self-host-status-page-only)** - Deploy only the status page without monitoring++### Related sections++- **[Tutorials](/docs/tutorial/getting-started)** - If you need step-by-step learning instead+- **[Explanations](/docs/concept/getting-started)** - To understand the concepts behind these guides+- **[Reference](/docs/reference)** - For detailed technical specificationsdiff --git a/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx b/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdxnew file mode 100644index 000000000..3de07b310--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx@@ -0,0 +1,78 @@+---+category: Guides+title: How to Deploy a Status Page to Cloudflare Pages+description: Learn how to use openstatus monitoring data to deploy a status page on Cloudflare Pages.+sidebar:+ label: Host your status page on Cloudflare Pages+---++## Problem++You need a fast, reliable, and automated status page, but you don't want to manage the hosting infrastructure. Manually updating a status page during an incident is inefficient and error-prone.++## Solution++Deploy a custom status page to Cloudflare's global edge network using openstatus as the data source. This guide shows you how to use our Astro-based template to create a status page that automatically reflects your monitoring data.++The code for the template is available on [GitHub](https://github.com/openstatusHQ/astro-status-page).++<Image+ src="/docs/guides/how-deploy-status-page-cf-pages/status-page.png"+ alt="Astro Status Page"+/>++## Prerequisites++- A Cloudflare account+- An [openstatus account](https://www.openstatus.dev) with at least one monitor configured.++## Step-by-step guide++### 1. Get your openstatus API key++First, you need an API key to fetch your monitoring data.++1. Navigate to your openstatus dashboard.+2. Go to **Settings** → **API Token**.+3. Click **Create API Key** and copy the key.++### 2. Set up the Astro project++Clone our status page template and install the dependencies.++```bash+git clone https://github.com/openstatusHQ/astro-status-page.git+cd astro-status-page+pnpm install+```++### 3. Customize the status page++You need to specify which monitors to display on your page.++1. Open the `src/pages/index.astro` file.+2. Find the following line of code:+ ```javascript+ const monitorIds = [1]+ ```+3. Replace the `1` with the ID of the monitor you want to display. You can find the monitor ID in the URL when you view a monitor in the openstatus dashboard (`/monitors/[ID]`). You can also add multiple IDs: `[1, 2, 5]`.++### 4. Configure your Cloudflare environment variable++Before deploying, you must provide your openstatus API key to Cloudflare.++1. Go to your Cloudflare dashboard and click on **Workers & Pages**.+2. Select your site and go to the **Settings** tab.+3. Navigate to **Environment variables** and add a new variable:+ - **Variable name**: `API_KEY`+ - **Value**: Paste your openstatus API key here.++### 5. Deploy to Cloudflare Pages++Now you can deploy your status page.++```bash+pnpm run pages:deploy+```++After the command completes, your status page will be live on Cloudflare Pages. 🎉diff --git a/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx b/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdxnew file mode 100644index 000000000..de8d8888f--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx@@ -0,0 +1,104 @@+---+category: Guides+title: How to Add a Status Badge to a GitHub README+description: A step-by-step guide to adding a real-time SVG or PNG status badge to your GitHub repository.+---++## Problem++You want to display the real-time status of your service directly in your GitHub repository's README file. This provides immediate visibility to your users and team members about the health of your application.++## Solution++openstatus provides embeddable status badges that you can add to any Markdown file, including your `README.md`. You can choose between a modern SVG badge or a legacy PNG badge.++## Prerequisites++- An openstatus account with a configured status page.+- The "slug" of your status page (the unique name in its URL, e.g., `https://[slug].openstatus.dev`).++## Step-by-step guide++### Step 1: Choose your badge type++We recommend using the modern SVG badge (v2) as it offers more customization options.++- **SVG Badge (v2)**: More flexible, better styling, and uses a monospaced font.+- **PNG Badge (Legacy)**: Simpler, but with fewer customization options.++### Step 2: Add the badge to your README++Copy the Markdown snippet for your chosen badge type and paste it into your `README.md` file. **Remember to replace `[slug]` with your status page slug.**++---++#### Option A: Modern SVG Badge (Recommended)++This is the recommended badge for most use cases.++##### Base URL++```+https://[slug].openstatus.dev/badge/v2+```++##### Markdown Snippet++```++```++**Example:**++++##### Customization++You can customize the badge by adding query parameters to the URL.++- **Theme**: `?theme=dark` (default is `light`)+- **Size**: `?size=md` (options: `sm`, `md`, `lg`, `xl`; default is `sm`)+- **Variant**: `?variant=outline` (adds a border; default has no border)++**Example with all options:**++```++```++---++#### Option B: Legacy PNG Badge++Use this badge if you prefer the older style.++##### Base URL++```+https://[slug].openstatus.dev/badge+```++##### Markdown Snippet++```markdown++```++**Example:**++++##### Customization++- **Theme**: `?theme=dark` (default is `light`)+- **Size**: `?size=lg` (options: `sm`, `md`, `lg`, `xl`; default is `sm`)++**Example with all options:**++```++```++### Step 3: Commit your changes++Save your `README.md` file and commit it to your repository. The status badge will now be visible to anyone visiting your repository. It will automatically update to reflect the current status of your services.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.mdxnew file mode 100644index 000000000..1a537a704--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx@@ -0,0 +1,140 @@+---+category: Guides+title: How to Deploy a Private Probe on Cloudflare Containers+description: A step-by-step guide to deploying an openstatus private monitoring probe on Cloudflare Containers.+sidebar:+ label: Deploy private probes on Cloudflare Containers+---+++## Problem++You need to monitor internal services that are not accessible from the public internet, or you want to run checks from your own infrastructure for compliance or performance reasons. You need a lightweight, serverless way to run these monitoring probes without managing virtual machines.++## Solution++Deploy the openstatus private location probe as a serverless container using Cloudflare Containers. This allows you to run monitoring checks from within your own network infrastructure, managed by Cloudflare. This guide will walk you through the entire process, from creating the private location in openstatus to deploying the container.++The code for the Cloudflare Worker template is available on [GitHub](https://github.com/openstatusHQ/private-location-cloudflare-container).++## Prerequisites+- A Cloudflare account+- An [openstatus account](https://www.openstatus.dev)+- `pnpm` and `docker` installed on your local machine++## Step-by-step guide++### 1. Create a private location in openstatus++First, you need to create a private location in your openstatus workspace to get an access key.++1. Go to the openstatus dashboard.+2. Click on **Private locations** in the sidebar.+3. Click **Create Private Location**.+4. Give it a human-readable name (e.g., "Cloudflare-EU").+5. Copy the generated token and save it somewhere secure.+6. Click **Submit** to save the new private location.++### 2. Set up the Cloudflare project++Next, create a new Cloudflare project using the containers template.++```bash+pnpm create cloudflare@latest --template=cloudflare/templates/containers-template+```++### 3. Pull and tag the probe Docker image++Pull the official openstatus private location image from Docker Hub. You must specify the `linux/amd64` platform, as this is what Cloudflare Containers supports.++```bash+# Pull the image+docker pull --platform linux/amd64 ghcr.io/openstatushq/private-location:latest++# Tag the image for Cloudflare (you cannot use the 'latest' tag)+docker tag ghcr.io/openstatushq/private-location:latest openstatus-private-location:v1+```++### 4. Push the image to Cloudflare Container Registry++Push the tagged image to your Cloudflare account's container registry.++```bash+pnpm wrangler containers push openstatus-private-location:v1+```++### 5. Configure `wrangler.toml`++Now, configure your Cloudflare project to use the container and run it on a schedule.++1. Open the `wrangler.toml` file.+2. Add a `[containers]` section to link the image you pushed. Replace `GENERATED_ID` with the actual ID from the previous step's output.+ ```toml+ [containers]+ image = "registry.cloudflare.com/GENERATED_ID/openstatus-private-location:v1"+ ```+3. Add a `triggers` section to run the worker on a cron schedule. This keeps the container alive, as Cloudflare Containers automatically scales to zero.+ ```toml+ triggers = { cron = ["*/2 * * * *"] } # Runs every 2 minutes+ ```++### 6. Configure the worker++Update the worker script (`index.ts`) to start the container with the correct environment variables.++1. Set the `sleepAfter` value to control how long the container runs after being invoked.+ ```typescript+ sleepAfter = "150s";+ ```+2. Update the `scheduled` function to pass your openstatus key to the container.+ ```typescript+ async scheduled(_controller: any, env: Env) {+ try {+ const container = getContainer(env.MY_CONTAINER);+ await container.start({+ envVars: {+ OPENSTATUS_KEY: env.OPENSTATUS_KEY,+ },+ });+ } catch (e) {+ console.error("Error in scheduled task:", e);+ }++ return new Response("ok");+ },+ ```++### 7. Add your openstatus key as a secret++Securely provide your private location token to the Cloudflare worker.++```bash+# Paste the token you saved in Step 1 when prompted+pnpm wrangler secret put OPENSTATUS_KEY+```++### 8. Deploy the application++Finally, deploy the worker and container to Cloudflare.++```bash+pnpm wrangler deploy+```++Your private location probe is now running on Cloudflare Containers and will start picking up monitoring jobs from your openstatus workspace.++## 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.++<Image+ src="/docs/guides/how-to-deploy-probes-cf-containters/cloudflare-log.png"+ alt="Cloudflare Workers Logs showing openstatus Private Location running"+ caption="Cloudflare Workers logs showing the private probe running."+ />++<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."+ />diff --git a/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx b/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdxnew file mode 100644index 000000000..9a18dbd74--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx@@ -0,0 +1,84 @@+---+category: Guides+title: How to Embed a Status Page in an Iframe+description: Embed a trimmed, chromeless version of your openstatus status page on any website using the `?embed` query parameter.+---++## Problem++You want to embed your openstatus status page in your marketing site, dashboard, or docs — without the full header, footer, and navigation that the standalone page includes.++## Solution++Append `?embed` to your status page URL to render a chromeless version suitable for embedding. Use the value to choose exactly which sections to show.++## URL contract++```+https://<your-slug>.openstatus.dev/?embed=<sections>+```++- The **value** `?embed=all` turns on embed mode and shows all sections. The header, navigation, and subscribe form are hidden. Non-whitelabel pages keep a compact "powered by openstatus.dev" attribution; whitelabel pages hide the footer entirely.+- The **value** can also be a comma-separated list of specific sections to show (e.g. `?embed=title,banner`).++### Sections++| Key | Renders |+|---|---|+| `title` | Page title + description |+| `banner` | Current incident / maintenance banner |+| `components` | Component health trackers |+| `feed` | Past status reports and maintenances |++Unknown keys are silently ignored. Section names are case-insensitive. If nothing valid is provided (e.g. `?embed=,` or `?embed=unknown`), all sections are shown.++Section keys apply to the **root status page URL only**. Other routes (`/monitors`, `/events`, `/events/report/:id`) accept `?embed` to hide header/footer chrome, but their content is unchanged — they render normally inside the frame.++### Additional parameters++| Param | Values | Behavior |+|---|---|---|+| `theme` | `light`, `dark` | Forces the theme. Honored only when `?embed` is present. Falls back to system preference, then the page's configured default. |++## Examples++Show the full chromeless page:++```html+<iframe+ src="https://status.example.com/?embed=all"+ width="100%"+ height="600"+ style="border: 0;"+></iframe>+```++Show only the title and current banner:++```html+<iframe+ src="https://status.example.com/?embed=title,banner"+ width="100%"+ height="300"+ style="border: 0;"+></iframe>+```++Show components in forced dark theme:++```html+<iframe+ src="https://status.example.com/?embed=components&theme=dark"+ width="100%"+ height="400"+ style="border: 0;"+></iframe>+```++## Notes and caveats++- **Height:** iframes do not auto-size to their content. Set a `height` attribute appropriate for the sections you enabled.+- **Internal links** (e.g. clicking an incident banner) open in a new tab when embedded, so your site's iframe stays put.+- **Password-protected status pages** may not authenticate correctly inside iframes due to browser third-party cookie restrictions (Safari ITP, Chrome). Visitors may need to authenticate on the full status page first.+- **Attribution:** non-whitelabel pages show a centered "powered by openstatus.dev" link in the embed footer. Whitelabel pages hide the footer entirely.+- **Sandboxed iframes** must include at least `allow-scripts allow-same-origin` for the status page to run, plus `allow-popups` for the "open in new tab" behavior on internal links.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.mdxnew file mode 100644index 000000000..6e2c8361a--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx@@ -0,0 +1,95 @@+---+category: Guides+title: How to Export Metrics to an OTLP Endpoint+description: A step-by-step guide to sending openstatus metrics to your observability platform via OTLP.+---+++## Problem++You want to analyze your openstatus monitoring data alongside other telemetry data in your existing observability platform (like Grafana, New Relic, or Honeycomb). You need a standardized way to export these metrics without building a custom integration.++## 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.++## 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.++## Step-by-step guide++### 1. Locate your OTLP endpoint URL and headers++First, you need to find the specific URL and any required authentication headers from your observability platform. This is usually found in the documentation under "OTLP," "OpenTelemetry," or "Metrics Export."++- **Endpoint URL**: Look for an HTTP endpoint for OTLP metrics. It will typically end 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:+ # ...+```++Replace `<YOUR_OTLP_ENDPOINT_URL>` and `<YOUR_TOKEN>` with the values you found in step 1.++**Note**: Currently, we only support OTLP over HTTP.++### 3. Apply the configuration++Use the openstatus CLI to apply the changes to your account.++```bash+openstatus monitors apply+```++After applying the configuration, openstatus will send metrics to your specified endpoint after every check is completed.++### 4. 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.++Here are some examples of what it can look like:++#### Grafana++<Image+ src="/docs/guides/how-to-export-metrics-via-otel/grafana.png"+ alt="openstatus metrics in grafana"+/>++#### Honeycomb++<Image+ src="/docs/guides/how-to-export-metrics-via-otel/honeycomb.jpg"+ alt="openstatus metrics in honeycomb"+/>++#### New Relic++<Image+ src="/docs/guides/how-to-export-metrics-via-otel/newrelic.jpg"+ alt="openstatus metrics in new-relic"+/>++#### SigNoz++<Image+ src="/docs/guides/how-to-export-metrics-via-otel/signoz.jpg"+ alt="openstatus metrics in signoz"+/>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.mdxnew file mode 100644index 000000000..8b0958d7f--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx@@ -0,0 +1,138 @@+---+category: Guides+title: How to Monitor Your Model Context Provider (MCP) Server+description: Learn how to monitor your MCP server with openstatus using JSON-RPC ping checks+sidebar:+ label: Monitor your MCP Server+---++## Problem: Ensuring Your MCP Server is Always Responsive++Running a Model Context Provider (MCP) server is critical for your AI applications, but traditional HTTP monitoring often falls short. MCP servers communicate using the JSON-RPC 2.0 protocol, requiring specific request/response patterns that standard health checks don't cover. How can you confidently ensure your MCP server is healthy and responsive at all times, without custom scripts or complex setups?++## Solution: JSON-RPC Ping Monitoring with openstatus++openstatus offers a robust solution for monitoring your MCP servers. By sending precise JSON-RPC `ping` requests to your endpoint from multiple global locations, openstatus verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide will walk you through setting up comprehensive monitoring for any MCP server using the openstatus CLI.++## Prerequisites++Before you begin, ensure you have:++- An [openstatus account](https://www.openstatus.dev/app/login).+- The [openstatus CLI installed](/docs/tutorial/get-started-with-openstatus-cli). (If you haven't installed it yet, follow this guide first).+- An MCP server with a publicly accessible endpoint.+- A basic understanding of the [JSON-RPC 2.0 protocol](https://www.jsonrpc.org/specification).++## Background: Understanding MCP for Monitoring++A Model Context Provider (MCP) is a crucial component that extends AI models with external context, data, or capabilities via the **Model Context Protocol (MCP)**. Essentially, it acts as a bridge, allowing AI models to interact with resources like databases, APIs, or file systems that aren't part of their core training.++### The MCP Server and JSON-RPC 2.0++## 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"}'+```++### 2. Understand the configuration++Let's break down the key fields in this YAML configuration:++- `name` & `description`: A human-readable name and explanation for your monitor.+- `frequency`: How often openstatus will run 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 localized 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.++### 3. Test your MCP server (Optional)++Before deploying your monitor, you can manually test your MCP server's `ping` endpoint with `curl` to confirm it responds as expected. This helps verify the `target` value for your `textBody` assertion.++```bash+curl -X POST \\+ -H "Content-Type: application/json" \\+ -d '{"jsonrpc": "2.0", "id": "openstatus", "method": "ping"}' \\+ https://hf.co/mcp # Replace with your MCP server URL+```++A healthy server should return a JSON response like `{"result":{},"jsonrpc":"2.0","id":"openstatus"}`.++### 4. Deploy your monitor++Once your `openstatus.yaml` file is ready, use the openstatus CLI to create the monitor:++```bash+openstatus create openstatus.yaml+```++This command uploads your configuration, and monitoring will begin immediately.++## Conclusion: Comprehensive MCP Server Monitoring Achieved++This guide has equipped you with the knowledge to effectively monitor your MCP server using openstatus. By leveraging YAML configuration and the openstatus CLI, you can ensure your critical AI infrastructure remains healthy and responsive.++## What You've Accomplished++- ✅ Successfully configured a JSON-RPC based monitor for your MCP server.+- ✅ Implemented precise assertions to validate `ping` responses.+- ✅ Set up global monitoring to detect localized or widespread issues.+- ✅ Automated monitor deployment using a version-controlled YAML configuration.++## Next Steps++Now that your MCP server is under robust monitoring, consider further enhancing your setup:+++- **[Export Metrics to OTLP](/docs/guides/how-to-export-metrics-to-otlp-endpoint)**: Integrate your MCP monitoring data with your existing observability platform for centralized analytics.+- **[Run Synthetic Tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)**: Incorporate these synthetic checks into your CI/CD pipeline for pre-deployment validation.++## Related Resources++- **[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 API reference for HTTP monitors.+- **[CLI Reference](/docs/reference/cli-reference)**: Full documentation for the openstatus CLI.diff --git a/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx b/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdxnew file mode 100644index 000000000..18129c3a6--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx@@ -0,0 +1,176 @@+---+category: Guides+title: How to Run Synthetic Tests in GitHub Actions+description: Integrate openstatus synthetic monitoring into your CI/CD pipeline+sidebar:+ label: GitHub Action for Synthetics+---++## Problem++You want to validate that your application's critical endpoints are working before deploying to production. Running synthetic tests in your CI/CD pipeline catches issues early and prevents broken deployments.++## Solution++openstatus provides a GitHub Action that runs your configured monitors as part of your CI/CD workflow. This guide shows you how to set it up.++## Prerequisites++- An [openstatus](https://www.openstatus.dev) account+- A GitHub repository+- At least one monitor configured in openstatus+- Admin access to your GitHub repository (for secrets)++## Step-by-step guide++### 1. Create a configuration file++Create a file named `openstatus.config.yaml` in your repository root:++```yaml+tests:+ ids:+ - 1+ - 2+```++**Finding monitor IDs:**+1. Go to your openstatus dashboard+2. Click on a monitor+3. The ID is in the URL: `https://www.openstatus.dev/app/[workspace]/monitors/[ID]`++**Tip:** Start with your most critical monitors and expand from there.++### 2. Get your openstatus API key++1. Go to your openstatus workspace settings+2. Navigate to the API section+3. Create a new API key or copy an existing one+4. Store it securely - you'll need it for the next step++### 3. Add your API key to GitHub Secrets++Secure your API key as a GitHub secret:++1. Go to your GitHub repository+2. Click **Settings** → **Secrets and variables** → **Actions**+3. Click **New repository secret**+4. Name: `OPENSTATUS_API_KEY`+5. Value: Your openstatus API key+6. Click **Add secret**++### 4. Create the GitHub Action workflow++Create `.github/workflows/openstatus.yml`:++```yaml+name: Run openstatus Synthetics CI++on:+ workflow_dispatch: # Manual trigger+ push:+ branches: [ main ] # Trigger on push to main+ pull_request: # Run on PRs (optional)++jobs:+ synthetic_ci:+ runs-on: ubuntu-latest+ name: Run openstatus Synthetics CI+ steps:+ - name: Checkout+ uses: actions/checkout@v4++ - name: Run openstatus Synthetics CI+ uses: openstatushq/openstatus-github-action@v1+ with:+ api_key: ${{ secrets.OPENSTATUS_API_KEY }}+```++### 5. Commit and push++```bash+git add openstatus.config.yaml .github/workflows/openstatus.yml+git commit -m "Add openstatus synthetic tests to CI"+git push origin main+```++The GitHub Action will run automatically on the next push to `main`.++## What you've accomplished++Great work! You've successfully:+- ✅ Integrated openstatus into your CI/CD pipeline+- ✅ Automated synthetic testing on every deployment+- ✅ Added a safety check before production releases+- ✅ Set up continuous validation of critical endpoints++## Customization options++### Run on different branches++```yaml+on:+ push:+ branches: [ main, staging, develop ]+```++### Run on pull requests++```yaml+on:+ pull_request:+ types: [opened, synchronize, reopened]+```++### Run on a schedule++```yaml+on:+ schedule:+ - cron: '0 */4 * * *' # Every 4 hours+```++### Multiple configuration files++```yaml+- name: Run openstatus Synthetics CI+ uses: openstatushq/openstatus-github-action@v1+ with:+ api_key: ${{ secrets.OPENSTATUS_API_KEY }}+ config_file: .openstatus/production.yaml+```++## Best practices++1. **Start small**: Begin with 2-3 critical monitors+2. **Fail fast**: Run synthetic tests early in your pipeline+3. **Monitor the monitors**: Track your synthetic test success rate+4. **Environment-specific**: Use different monitors for staging vs production+5. **Document failures**: Investigate and document any CI failures++## Troubleshooting++**Action fails with authentication error:**+- Verify `OPENSTATUS_API_KEY` secret is set correctly+- Check that your API key hasn't expired++**Monitors not found:**+- Confirm monitor IDs are correct in `openstatus.config.yaml`+- Ensure monitors are active in your openstatus dashboard++**Tests timing out:**+- Check that your endpoints are accessible from GitHub's runners+- Consider increasing timeouts in monitor configuration++## Next steps++- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Advanced monitoring examples+- **[Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** - Manage monitors with YAML+- **[CLI Reference](/docs/reference/cli-reference)** - Automate monitor management+- **[Export Metrics](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** - Send data to your observability platform++## Related resources++- **[GitHub Action on Marketplace](https://github.com/marketplace/actions/openstatus-synthetics-ci)** - Official action+- **[Example Repository](https://github.com/openstatusHQ/github-action-example)** - Working examples+- **[Join Discord](https://www.openstatus.dev/discord)** - Get help from the communitydiff --git a/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdxnew file mode 100644index 000000000..b43b94188--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx@@ -0,0 +1,87 @@+---+category: Guides+title: How to translate your status page+description: Enable multiple languages on your status page and contribute new translations.+---++openstatus status pages support multiple languages. You can configure which locales are available per page and set a default language. Visitors can switch between languages using a built-in locale switcher.++:::note+Translations are available on paid plans only.+:::++## Supported locales++Currently supported languages:++| Code | Language |+|------|----------|+| `en` | English |+| `fr` | Français |+| `de` | Deutsch |+| `tr` | Türkçe |+| `hi` | हिंदी |++## Enable translations on your status page++1. Go to your **Dashboard** and open the status page settings.+2. Under **Locales**, select a **Default Locale** for your page.+3. Check **Enable locale switcher** to allow visitors to switch languages.+4. Select which languages you want to offer.+5. Click **Submit**.++When the locale switcher is enabled, visitors will see a language dropdown on your status page. The default locale is omitted from the URL for cleaner paths (e.g., `/status` instead of `/status/en`), while non-default locales are included (e.g., `/status/fr`).++## How routing works++openstatus supports two routing modes for locales:++- **Pathname routing** (subdomains like `status.openstatus.dev`): the locale appears after the slug, e.g., `/status/fr/events`.+- **Hostname routing** (custom domains like `status.example.com`): the locale is the first path segment, e.g., `/fr/events`.++In both cases, the default locale is omitted from the URL (`as-needed` prefix strategy).++## Contributing a new locale++Translations are open source. To add a new language:++### 1. Extend the locale registry++Add your locale to `packages/locales/index.ts`:++```ts+import type { Locale as DateFnsLocale } from "date-fns/locale";+import { de, enUS, fr, hi, tr } from "date-fns/locale";++export const locales = ["en", "fr", "de", "tr", "hi"] as const;+// ...+export const localeDetails: Record<Locale, { name: string; flag: string }> = {+ en: { name: "English", flag: "🇺🇸" },+ fr: { name: "Français", flag: "🇫🇷" },+ de: { name: "Deutsch", flag: "🇩🇪" },+ tr: { name: "Türkçe", flag: "🇹🇷" },+ hi: { name: "हिंदी", flag: "🇮🇳" },+};++export const dateFnsLocales: Record<Locale, DateFnsLocale> = {+ en: enUS,+ fr,+ de,+ tr,+ hi,+};+```++### 2. Generate the translation file++Run the status page dev server:++```bash+pnpm dev:status-page+```++The `next-intl` extraction plugin will automatically create a new `apps/status-page/messages/<locale>.json` file with all translation keys pre-populated from the source locale. You can then fill in the translations.++### 3. Submit a pull request++Once your translations are complete, submit a PR to the [openstatus repository](https://github.com/openstatusHQ/openstatus). The locale will become available to all status pages after the next deployment.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.mdxnew file mode 100644index 000000000..a95299ce0--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx@@ -0,0 +1,74 @@+---+category: Guides+title: How to Use openstatus React Widget+description: Add an openstatus status widget to your React or Next.js app with the @openstatus/react package, as a server or client component.+---++Install the [npm](https://www.npmjs.com/package/@openstatus/react) package:++```bash+npm install @openstatus/react+```++## React Server Component++```tsx+import { StatusWidget } from "@openstatus/react";++export function Page() {+ return <StatusWidget slug="status" />;+}+```++It will automatically attach the slug to the href to allow the user to open a+new tab on click to `https://slug.openstatus.dev`. If you want to redirect him+to a specific page, use the `href` property, like so:++```tsx+<StatusWidget slug="documenso" href="https://status.documenso.com" />+```++> `StatusWidget` is an **async function** and will only work with RSC. Using it+> within a dead simple React App will not work.++### Styling++#### With tailwindcss++```ts+// tailwind.config.js+module.exports = {+ content: [+ "./app/**/*.{tsx,ts,mdx,md}",+ "./node_modules/@openstatus/react/**/*.{js,ts,jsx,tsx}",+ ],+ theme: {+ extend: {},+ },+ plugins: [],+};+```++#### Without tailwindcss++```tsx+// app/layout.tsx+import "@openstatus/react/dist/styles.css";+```++## Typed fetch function++```tsx+import { getStatus } from "@openstatus/react";++// React Server Component+async function CustomStatusWidget() {+ const res = await getStatus("slug");+ // ^StatusResponse = { status: Status }++ const { status } = res;+ // ^Status = "unknown" | "operational" | "degraded_performance" | "partial_outage" | "major_outage" | "under_maintenance" | "incident"++ return <div>{/* customize */}</div>;+}+```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.mdxnew file mode 100644index 000000000..2cc3ebc08--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx@@ -0,0 +1,146 @@+---+category: Guides+title: Self-Host the openstatus Status Page (Lightweight)+description: Deploy only the openstatus status page and dashboard on your own infrastructure, without monitoring, analytics, or background services.+---++## Problem++You want a status page to communicate incidents and maintenance to your users, but you don't need automated monitoring, analytics, or alerting. You may already have your own monitoring tools, or you simply want a lightweight way to manage your public-facing status page.++## Solution++openstatus provides a lightweight Docker Compose setup that runs only 4 services: a database, a one-shot migration runner, the dashboard, and the status page. This is ideal for teams who only want to self-host the status page without monitoring, or for teams that manage incidents manually using external monitoring tools.++## Lightweight vs Full++The lightweight stack strips away all monitoring infrastructure. Here's what each version includes:++| Feature | Full | Lightweight |+|---------|------|-------------|+| Status page | Yes | Yes |+| Dashboard | Yes | Yes |+| Database (libSQL) | Yes | Yes |+| Automated monitoring | Yes | **No** |+| Analytics & charts (Tinybird) | Yes | **No** |+| API server | Yes | **No** |+| Private location probes | Yes | **No** |++If you need automated monitoring, follow the [full self-hosting guide](/docs/guides/self-hosting-openstatus) instead.++## Prerequisites++- Docker and Docker Compose installed+- Git installed+- Command line experience++## Step-by-step guide++### Part 1: Initial Setup and Service Launch++1. **Clone the Repository**++ Get the latest version of openstatus:+ ```bash+ git clone https://github.com/openstatushq/openstatus+ cd openstatus+ ```++2. **Configure Your Environment**++ Copy the example environment file. This is a simplified version of the full configuration, with only the variables relevant to the status page and dashboard.+ ```bash+ cp .env.docker-lightweight.example .env.docker+ ```+ Open `.env.docker` in a text editor. You **must** set values for the following variables:++ - `AUTH_SECRET` — required for authentication. Generate a value with:+ ```bash+ openssl rand -base64 32+ ```+ - `RESEND_API_KEY` — required for magic link login emails. Get a key from [resend.com](https://resend.com).++ Optionally, you can configure GitHub or Google OAuth providers by filling in the `AUTH_GITHUB_*` or `AUTH_GOOGLE_*` variables in the same file.++3. **Build and Start Services**++ Use Docker Compose to build and run all services in the background:+ ```bash+ docker compose -f docker-compose-lightweight.yaml up -d+ ```++ The first build takes several minutes as it compiles the Next.js applications. Subsequent starts are much faster.++ Check the status of the services:+ ```bash+ docker compose -f docker-compose-lightweight.yaml ps+ ```++ Wait until all services show as `healthy` before proceeding. The `db-migrate` service will show as exited — this is expected, as it runs once and stops.++### Part 2: Application Configuration++4. **Access the Applications**++ - **Dashboard:** `http://localhost:3000`+ - **Status Page:** `http://localhost:3001`++ Log in to the dashboard using email authentication (magic link). This will create your account and workspace.++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`:++ ```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"]}'+ ```++ You can find your workspace ID by querying the database:+ ```bash+ curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \+ -d '{"statements":["SELECT id, name FROM workspace"]}'+ ```++6. **Create Your Status Page**++ In the dashboard, create a new status page, add components for the services you want to display, and publish it. Your status page will be available at `http://localhost:3001`.++## Service architecture++| Service | Container | Host Port | Purpose |+|---------|-----------|-----------|---------|+| libsql | openstatus-libsql | 8080 | Database (HTTP API) |+| db-migrate | openstatus-db-migrate | — | One-shot database migration (exits after completion) |+| dashboard | openstatus-dashboard | 3000 | Admin interface |+| status-page | openstatus-status-page | 3001 | Public status page |++## Data persistence++All application data is stored in the `openstatus-libsql-data` Docker volume.++- `docker compose down` **preserves** your data.+- `docker compose down -v` **destroys** the volume and all data.++For production use, back up this volume regularly.++## Troubleshooting++**Containers won't start:** Check the logs for the failing service:+```bash+docker compose -f docker-compose-lightweight.yaml logs <service-name>+```++**Magic link emails not arriving:** Verify that `RESEND_API_KEY` is set correctly in `.env.docker`.++**Dashboard shows errors on first load:** The `db-migrate` service may still be running. Check its status:+```bash+docker compose -f docker-compose-lightweight.yaml ps+```++**Port conflicts:** If ports 3000, 3001, or 8080 are already in use on your machine, update the host port mappings in `docker-compose-lightweight.yaml`. For example, change `"3000:3000"` to `"4000:3000"` to use port 4000 instead.++## Next steps++- **[Self-Host openstatus (Full)](/docs/guides/self-hosting-openstatus)** — Add automated monitoring, analytics, and alerting+- **[Join our Discord](https://www.openstatus.dev/discord)** — Get help from the communitydiff --git a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdxnew file mode 100644index 000000000..9ebe5066c--- /dev/null+++ b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx@@ -0,0 +1,221 @@+---+category: Guides+title: How to Self-Host openstatus+description: Complete guide to deploying openstatus on your own infrastructure+---++++## Problem++You want to run openstatus on your own infrastructure instead of using the hosted service. This gives you full control over your data, customization options, and the ability to monitor internal services not accessible from the public internet.++## Solution++openstatus provides a Docker Compose setup that makes self-hosting straightforward. This guide walks you through deploying all necessary services and configuring your self-hosted instance.++## Prerequisites++- Docker and Docker Compose installed+- Basic understanding of Docker and containerization+- Command line experience+- Git installed++## Known limitations++Self-hosting openstatus currently has these constraints:++- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.+- **IP Restriction is not secure outside Vercel.** The IP restriction feature for status pages relies on the `X-Forwarded-For` header, which [Vercel overwrites with the verified client IP](https://vercel.com/docs/headers/request-headers#x-forwarded-for). When self-hosting behind a different reverse proxy, clients can spoof this header to bypass IP restrictions. If you self-host and use IP restriction, ensure your reverse proxy strips and rewrites `X-Forwarded-For` with the real client IP before forwarding to openstatus.++## Step-by-step guide++This guide is divided into three parts: launching the services, setting up the database and analytics, and configuring the application through the UI.++### Part 1: Initial Setup and Service Launch++1. **Clone the Repository**++ Get the latest version of openstatus:+ ```bash+ git clone https://github.com/openstatushq/openstatus+ cd openstatus+ ```++2. **Configure Your Environment**++ Copy the example environment file. This file will hold all your configuration variables.+ ```bash+ cp .env.docker.example .env.docker+ ```+ Open `.env.docker` in a text editor. At a minimum, you **must** set a value for `AUTH_SECRET` for authentication to work. For a complete setup, review the file for other variables like OAuth providers or email services.++3. **Build and Start Services**++ Use Docker Compose to build and run all openstatus services in the background.+ ```bash+ export DOCKER_BUILDKIT=1+ docker compose up -d+ ```+ You can check the status of the services with `docker compose ps`. It might take a few minutes for all services to be healthy.++### Part 2: Database and Analytics Setup++4. **Run Database Migrations**++ The database container starts with an empty database. You must run migrations to set up the required schema.+ ```bash+ # Make sure you are in the root of the openstatus project+ cd packages/db+ pnpm install+ pnpm migrate+ cd ../.. # Return to the project root+ ```++ If you do not have or want to avoid installing the necessary tools on the host, you can run this command to create a one-shot container that will remove itself after completion.+ ```+ # Make sure you are in the root of the openstatus project+ # For RHEL derivatives, make sure to end /work with :Z for SELinux, "$PWD":/work:Z+ sudo docker run --rm -it \+ --network openstatus \+ --env-file .env.docker \+ -v "$PWD":/work \+ -w /work/packages/db \+ node:22-trixie \+ bash -lc '+ set -euo pipefail+ export DEBIAN_FRONTEND=noninteractive+ apt-get update -qq+ apt-get install -y -qq curl ca-certificates unzip+ curl -fsSL https://bun.sh/install -o /tmp/bun-install.sh+ bash /tmp/bun-install.sh+ export PATH="$HOME/.bun/bin:$PATH"+ npm i -g pnpm+ pnpm install+ bun src/migrate.mts+ '+ ```++5. **Deploy Local Tinybird Analytics**++ Tinybird is used for analytics. Deploy the local datasources, pipes, and endpoints.+ ```bash+ # Make sure you are in the root of the openstatus project+ cd packages/tinybird+ pnpm install+ tb --local deploy+ cd ../.. # Return to the project root+ ```++6. **Configure Tinybird API Key**++ You need to get your local Tinybird admin token and add it to your environment file.+ ```bash+ cd packages/tinybird+ tb --local open # This opens the Tinybird UI in your browser+ ```+ In the Tinybird UI, find and copy your admin token. Then, add it to your `.env.docker` file in the root of the project:+ ```env+ TINY_BIRD_API_KEY="your-tinybird-admin-token"+ ```+ After adding the token, restart your services for the changes to take effect:+ ```bash+ # Make sure you are in the root of the openstatus project+ docker compose restart+ ```++### Part 3: Application Configuration++Now that the services are running, you can access the dashboard and perform the final setup steps.++- **Dashboard:** `http://localhost:3002`+- **Status Pages:** `http://localhost:3003`++7. **Create a Workspace and Set Limits**++ - Navigate to the dashboard at `http://localhost:3002`.+ - 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.+ ```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"]}'+ ```+ 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"]}'`.++ If you want to unlock the paid features, you need to upgrade your workspace inside the database. The following command assumes that you want to change the payment plan for the workspace with the ID of 1, and that you want to change it to a "Pro" instance indefinitely.+ ```+ curl -sS -X POST "http://localhost:8080/" \+ -H "Content-Type: application/json" \+ -d "{\"statements\":[+ \"UPDATE workspace SET plan='team', paid_until=strftime('%s','now') + 315360000, ends_at=NULL WHERE id=1;\",+ \"SELECT id, plan, paid_until, ends_at FROM workspace WHERE id=1;\"+ ]}"+ ```++8. **Deploy a Private Location**++ The self-hosted version relies on private locations to perform checks.+ - In the dashboard, navigate to **Settings -> Private Locations** and create a new one.+ - Copy the generated `OPENSTATUS_KEY`.+ - Deploy the private location probe to your infrastructure using the Docker image `ghcr.io/openstatushq/private-location:latest`.+ - When deploying, you must provide two environment variables to the container:+ - `OPENSTATUS_KEY`: The key you just copied.+ - `OPENSTATUS_INGEST_URL`: The URL of your self-hosted server's API endpoint (e.g., `http://<your-server-ip-or-domain>:3001`).+ - For a detailed guide on deploying a private location, see **[Deploy Private Locations on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)**.++9. **Create Monitors**++ You're all set! You can now create monitors in the dashboard. They will be checked by the private location you deployed.+++ <Image+ src="/docs/guides/self-hosting-openstatus/local-openstatus.png"+ alt="openstatus running locally with self-hosted services"+ />+++## Service architecture++openstatus consists of multiple services running together:++| Service | Port | Purpose |+|---------|------|---------|+| workflows | 3000 | Background jobs and scheduled tasks |+| server | 3001 | API backend (tRPC) |+| dashboard | 3002 | Admin interface for configuration |+| status-page | 3003 | Public status pages |+| private-location | 8081 | Monitoring agent for checks |+| libsql | 8080 | Database (HTTP) |+| libsql | 5001 | Database (gRPC) |+| tinybird-local | 7181 | Analytics and metrics |++## What you've accomplished++Congratulations! You've successfully:+- ✅ Deployed openstatus on your own infrastructure+- ✅ Configured all required services+- ✅ Set up a private location for monitoring+- ✅ Created your first self-hosted monitor++## Troubleshooting++**Containers won't start**: Check Docker logs with `docker compose logs [service-name]`++**Database migrations fail**: Ensure you're in the correct directory and have pnpm installed++**Private location not connecting**: Verify the `OPENSTATUS_KEY` and `OPENSTATUS_INGEST_URL` are correct++**Tinybird issues**: Make sure the Tinybird token is correctly set in `.env.docker`++## Next steps++- **[Deploy Private Locations](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - Set up monitoring from multiple regions+- **[Create Monitors](/docs/tutorial/how-to-create-monitor)** - Start monitoring your services++## Additional resources++- **[Docker Compose file](https://github.com/openstatusHQ/openstatus/blob/main/docker-compose.yaml)** - Review the complete configuration+- **[Private Location Reference](/docs/reference/private-location)** - Technical specifications+- **[Join our Discord](https://www.openstatus.dev/discord)** - Get help from the communitydiff --git a/apps/web/src/content/pages/docs/help/support.mdx b/apps/web/src/content/pages/docs/help/support.mdxnew file mode 100644index 000000000..4201a313c--- /dev/null+++ b/apps/web/src/content/pages/docs/help/support.mdx@@ -0,0 +1,11 @@+---+category: Help+title: Need help?+description: "We're always here to help."+---++If you have any questions, feedback, or need help you can:+- Schedule a [call](https://cal.com/team/openstatus/30min) with us.+- Join our [Discord](https://www.openstatus.dev/discord) community.+- Send us an email at [[email protected]](mailto:[email protected])+- Open an issue on our [GitHub](https://www.github.com/openstatushq/openstatus) repository.\ No newline at end of filediff --git a/apps/web/src/content/pages/docs/reference/cli-reference.mdx b/apps/web/src/content/pages/docs/reference/cli-reference.mdxnew file mode 100644index 000000000..61d942a40--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/cli-reference.mdx@@ -0,0 +1,640 @@+---+category: Reference+title: CLI Reference+description: Complete reference for the openstatus CLI — manage status pages, monitors, and incidents from your terminal.+---++## CLI interface - openstatus++Manage status pages, monitors, and incidents from the terminal.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] [COMMAND] [COMMAND FLAGS] [ARGUMENTS...]+```++Global flags:++| Name | Description | Default value | Environment variables |+|------------------|---------------------------|:-------------:|:---------------------:|+| `--json` | Output results as JSON | `false` | *none* |+| `--no-color` | Disable colored output | `false` | *none* |+| `--quiet` (`-q`) | Suppress non-error output | `false` | *none* |+| `--debug` | Enable debug output | `false` | *none* |++### `monitors` command (aliases: `m`)++Manage your monitors.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors [ARGUMENTS...]+```++### `monitors apply` subcommand++Create or update monitors.++> openstatus monitors apply+> openstatus monitors apply --config custom.yaml -y+> openstatus monitors apply --dry-run++Creates or updates monitors according to the openstatus configuration file. Compares your openstatus.yaml with the current state and applies changes.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors apply [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------------------|:-----------------:|:----------------------:|+| `--config="…"` (`-c`) | The configuration file containing monitor information | `openstatus.yaml` | *none* |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |+| `--dry-run` (`-n`) | Show what would be changed without applying | `false` | *none* |++### `monitors create` subcommand++Create monitors.++> openstatus monitors create+> openstatus monitors create --config custom.yaml -y++Create the monitors defined in the openstatus.yaml file.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors create [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------------------|:-----------------:|:----------------------:|+| `--config="…"` (`-c`) | The configuration file containing monitor information | `openstatus.yaml` | *none* |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |++### `monitors delete` subcommand++Delete a monitor.++> openstatus monitors delete MonitorID+> openstatus monitors delete 12345 -y++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors delete [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|---------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |++### `monitors import` subcommand++Import all your monitors.++> openstatus monitors import+> openstatus monitors import --output monitors.yaml++Import all your monitors from your workspace to a YAML file; it will also create a lock file to manage your monitors with 'apply'.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors import [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-----------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--output="…"` (`-o`) | The output file name | `openstatus.yaml` | *none* |++### `monitors info` subcommand++Get a monitor information.++> openstatus monitors info MonitorID+> openstatus monitors info 12345+> openstatus monitors info 12345 --time-range 7d++Fetch the monitor information including configuration, live status per region, and summary metrics.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors info [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|----------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--time-range="…"` | Time range for summary metrics (1d, 7d, 14d) | `1d` | *none* |++### `monitors list` subcommand++List all monitors.++> openstatus monitors list+> openstatus monitors list --all++List all monitors. The list shows all your monitors attached to your workspace. It displays the ID, name, URL, and kind of each monitor.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors list [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------|:-------------:|:----------------------:|+| `--all` | List all monitors including inactive ones | `false` | *none* |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `monitors trigger` subcommand++Trigger a monitor execution.++> openstatus monitors trigger MonitorID+> openstatus monitors trigger 12345++Trigger a monitor execution on demand. This command allows you to launch your tests on demand.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] monitors trigger [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `status-report` command (aliases: `sr`)++Manage status reports.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report [ARGUMENTS...]+```++### `status-report list` subcommand++List all status reports.++> openstatus status-report list+> openstatus status-report list --status investigating --limit 10++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report list [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|--------------------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--status="…"` | Filter by status (investigating, identified, monitoring, resolved) | | *none* |+| `--limit="…"` | Maximum number of reports to return (1-100) | `0` | *none* |++### `status-report info` subcommand++Get status report details.++> openstatus status-report info ReportID+> openstatus status-report info 12345++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report info [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `status-report create` subcommand++Create a status report.++> openstatus status-report create --title "API Degradation" --status investigating --message "Investigating increased latency" --page-id 123++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report create [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|------------------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--title="…"` | Title of the status report | | *none* |+| `--status="…"` | Initial status (investigating, identified, monitoring, resolved) | | *none* |+| `--message="…"` | Initial message describing the incident | | *none* |+| `--page-id="…"` | Status page ID to associate with this report | | *none* |+| `--component-ids="…"` | Comma-separated page component IDs | | *none* |+| `--notify` | Notify subscribers about this status report | `false` | *none* |+| `--date="…"` | Date when the event occurred (RFC 3339 format, defaults to now) | | *none* |++### `status-report update` subcommand++Update status report metadata.++> openstatus status-report update ReportID [--title "New title"] [--component-ids id1,id2]++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report update [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--title="…"` | New title for the report | | *none* |+| `--component-ids="…"` | Comma-separated page component IDs (replaces existing list) | | *none* |++### `status-report delete` subcommand++Delete a status report.++> openstatus status-report delete ReportID+> openstatus status-report delete 12345 -y++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report delete [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|---------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |++### `status-report add-update` subcommand++Add an update to a status report.++> openstatus status-report add-update ReportID --status resolved --message "Issue has been resolved"++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-report add-update [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|--------------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--status="…"` | New status (investigating, identified, monitoring, resolved) | | *none* |+| `--message="…"` | Message describing what changed | | *none* |+| `--date="…"` | Date for the update (RFC 3339 format, defaults to now) | | *none* |+| `--notify` | Notify subscribers about this update | `false` | *none* |++### `maintenance` command (aliases: `mt`)++Manage maintenance windows.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance [ARGUMENTS...]+```++### `maintenance list` subcommand++List all maintenance windows.++> openstatus maintenance list+> openstatus maintenance list --page-id abc --limit 10++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance list [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|--------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--page-id="…"` | Filter by status page ID | | *none* |+| `--limit="…"` | Maximum number of maintenances to return (1-100) | `0` | *none* |++### `maintenance info` subcommand++Get maintenance window details.++> openstatus maintenance info MaintenanceID+> openstatus maintenance info 12345++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance info [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `maintenance create` subcommand++Create a maintenance window.++> openstatus maintenance create --title "DB Migration" --message "Upgrading database" --from 2026-04-01T10:00:00Z --to 2026-04-01T12:00:00Z --page-id 123++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance create [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|--------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--title="…"` | Title of the maintenance | | *none* |+| `--message="…"` | Message describing the maintenance | | *none* |+| `--from="…"` | Start time of the maintenance window (RFC 3339 format) | | *none* |+| `--to="…"` | End time of the maintenance window (RFC 3339 format) | | *none* |+| `--page-id="…"` | Status page ID to associate with this maintenance | | *none* |+| `--component-ids="…"` | Comma-separated page component IDs | | *none* |+| `--notify` | Notify subscribers about this maintenance | `false` | *none* |++### `maintenance update` subcommand++Update a maintenance window.++> openstatus maintenance update MaintenanceID [--title "New title"] [--message "New message"] [--from ...] [--to ...]++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance update [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--title="…"` | New title for the maintenance | | *none* |+| `--message="…"` | New message for the maintenance | | *none* |+| `--from="…"` | New start time (RFC 3339 format) | | *none* |+| `--to="…"` | New end time (RFC 3339 format) | | *none* |+| `--component-ids="…"` | Comma-separated page component IDs (replaces existing list) | | *none* |++### `maintenance delete` subcommand++Delete a maintenance window.++> openstatus maintenance delete MaintenanceID+> openstatus maintenance delete 12345 -y++Usage:++```bash+$ openstatus [GLOBAL FLAGS] maintenance delete [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|---------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |++### `status-page` command (aliases: `sp`)++Manage status pages.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-page [ARGUMENTS...]+```++### `status-page list` subcommand++List all status pages.++> openstatus status-page list+> openstatus status-page list --limit 10++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-page list [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--limit="…"` | Maximum number of pages to return (1-100) | `0` | *none* |++### `status-page info` subcommand++Get status page details.++> openstatus status-page info PageID+> openstatus status-page info 12345++Usage:++```bash+$ openstatus [GLOBAL FLAGS] status-page info [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `notification` command (aliases: `n`)++Manage notifications.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] notification [ARGUMENTS...]+```++### `notification list` subcommand++List all notifications.++> openstatus notification list+> openstatus notification list --limit 10++Usage:++```bash+$ openstatus [GLOBAL FLAGS] notification list [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|---------------------------------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--limit="…"` | Maximum number of notifications to return (1-100) | `0` | *none* |++### `notification info` subcommand++Get notification details.++> openstatus notification info NotificationID+> openstatus notification info 12345++Usage:++```bash+$ openstatus [GLOBAL FLAGS] notification info [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `run` command (aliases: `r`)++Run your uptime tests.++> openstatus run+> openstatus run --config custom-config.yaml++Run the uptime tests defined in the config.openstatus.yaml. The config file should be in the following format: tests: ids: - monitor-id-1 - monitor-id-2.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] run [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:------------------------:|:----------------------:|+| `--config="…"` | The configuration file | `config.openstatus.yaml` | *none* |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `whoami` command (aliases: `w`)++Get your workspace information.++> openstatus whoami++Get your current workspace information. Displays the workspace name, slug, and plan.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] whoami [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------|:-------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |++### `login` command++Save your API token.++> openstatus login++Saves your openstatus API token for use in subsequent commands. Get your API token from the openstatus dashboard.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] login [ARGUMENTS...]+```++### `logout` command++Remove saved API token.++> openstatus logout++Usage:++```bash+$ openstatus [GLOBAL FLAGS] logout [ARGUMENTS...]+```++### `terraform` command (aliases: `tf`)++Generate Terraform configuration.++Usage:++```bash+$ openstatus [GLOBAL FLAGS] terraform [ARGUMENTS...]+```++### `terraform generate` subcommand (aliases: `gen`)++Generate Terraform configuration from workspace resources.++> openstatus terraform generate [--output-dir ./openstatus-terraform/]++Usage:++```bash+$ openstatus [GLOBAL FLAGS] terraform generate [COMMAND FLAGS] [ARGUMENTS...]+```++The following flags are supported:++| Name | Description | Default value | Environment variables |+|-----------------------------|-----------------------------------------|:-------------------------:|:----------------------:|+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--output-dir="…"` (`-o`) | Directory to write Terraform files into | `./openstatus-terraform/` | *none* |diff --git a/apps/web/src/content/pages/docs/reference/dns-monitor.mdx b/apps/web/src/content/pages/docs/reference/dns-monitor.mdxnew file mode 100644index 000000000..3b79e12e3--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/dns-monitor.mdx@@ -0,0 +1,132 @@+---+category: Reference+title: DNS Monitor Reference+description: Complete technical specification for DNS record monitoring+---++## Overview++A DNS Monitor is a component designed to verify the availability and correctness of DNS records. It performs periodic lookups for specified DNS record types against a target domain or subdomain from various geographical locations.++**Use cases:**+- Validating domain name resolution+- Monitoring changes to critical DNS records (e.g., A, CNAME, MX)+- Ensuring proper load balancing via DNS (when combined with multi-region checks)+- Detecting unauthorized DNS alterations++## Configuration++### URI++**Type:** String (required)+**Format:** Domain name or subdomain++The fully qualified domain name or subdomain to be monitored.++**Examples:**+- `openstat.us`+- `api.example.com`+- `mail.example.org`++### Record Types++The monitor supports fetching and validating the following DNS record types:++- `A` (Address Record): Maps a domain name to an IPv4 address.+- `AAAA` (IPv6 Address Record): Maps a domain name to an IPv6 address.+- `CNAME` (Canonical Name Record): Maps an alias domain name to another canonical domain name.+- `MX` (Mail Exchange Record): Specifies the mail servers responsible for accepting email messages on behalf of a domain name.+- `NS` (Name Server Record): Delegates a domain or subdomain to a set of authoritative name servers.+- `TXT` (Text Record): Carries arbitrary human-readable text and is also used for various purposes like SPF, DKIM, DMARC, and site verification.++### Regions++The geographical locations from which the DNS monitoring checks are performed. This allows for verification of DNS propagation and performance across different networks.++__Africa__++- Johannesburg, South Africa 🇿🇦 (free)++__Asia__++- Hong Kong, Hong Kong 🇭🇰 (free)+- Mumbai, India 🇮🇳+- Singapore, Singapore 🇸🇬+- Tokyo, Japan 🇯🇵++__Europe__++- Amsterdam, Netherlands 🇳🇱 (free)+- Bucharest, Romania 🇷🇴+- Frankfurt, Germany 🇩🇪+- London, United Kingdom 🇬🇧+- Madrid, Spain 🇪🇸+- Paris, France 🇫🇷+- Stockholm, Sweden 🇸🇪+- Warsaw, Poland 🇵🇱++__North America__++- Ashburn, Virginia, USA 🇺🇸 (free)+- Atlanta, Georgia, USA 🇺🇸+- Boston, Massachusetts, USA 🇺🇸+- Chicago, Illinois, USA 🇺🇸+- Dallas, Texas, USA 🇺🇸+- Denver, Colorado, USA 🇺🇸+- Guadalajara, Mexico 🇲🇽+- Los Angeles, California, USA 🇺🇸+- Miami, Florida, USA 🇺🇸+- Montreal, Canada 🇨🇦+- Phoenix, Arizona, USA 🇺🇸+- Queretaro, Mexico 🇲🇽+- Seattle, Washington, USA 🇺🇸+- San Jose, California, USA 🇺🇸+- Toronto, Canada 🇨🇦++__South America__++- Bogota, Colombia 🇨🇴+- Buenos Aires, Argentina 🇦🇷+- Rio de Janeiro, Brazil 🇧🇷+- Sao Paulo, Brazil 🇧🇷 (free)+- Santiago, Chile 🇨🇱++__Oceania__++- Sydney, Australia 🇦🇺 (free)++### Frequency++The interval at which the DNS checks are performed. Supported frequencies:+- 30 seconds+- 1 minute+- 5 minutes+- 10 minutes+- 30 minutes+- 1 hour++### Response Time Thresholds++#### Timeout++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for a DNS response. If the lookup exceeds this time, the check is considered failed.++#### Degraded++**Type:** Duration (optional)++The duration after which a DNS response is considered degraded. This indicates a performance issue without being a complete failure.++### Retry++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will retry a failed DNS lookup before reporting a definitive failure. For example: `3`++## Related resources++- **[CLI Reference](/docs/reference/cli-reference)** - Manage monitors as code using the openstatus CLI.diff --git a/apps/web/src/content/pages/docs/reference/http-monitor.mdx b/apps/web/src/content/pages/docs/reference/http-monitor.mdxnew file mode 100644index 000000000..f1e70c4c5--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/http-monitor.mdx@@ -0,0 +1,277 @@+---+category: Reference+title: HTTP Monitor Reference+description: Complete technical specification for HTTP/HTTPS endpoint monitoring+---++## Overview++An HTTP Monitor is a component that allows you to monitor the status of HTTP and HTTPS endpoints. It can be used to monitor websites, APIs, webhooks, or any other HTTP-accessible service.++**Use cases:**+- Website uptime monitoring+- API health checks+- Webhook endpoint validation+- CDN performance monitoring+- Authentication endpoint testing++## Configuration++### URL++**Type:** String (required)+**Format:** Full URL including protocol++The URL of the HTTP endpoint you want to monitor.++**Examples:**+- `https://openstat.us`+- `https://api.example.com/health`+- `http://internal-service.local:8080/status`++**Note:** We recommend using HTTPS for better security.++### Methods++**Type:** String (required)+**Default:** `GET`++The HTTP method to use when making the request to the endpoint.++**Available methods:**+- `GET` - Retrieve data (most common for health checks)+- `POST` - Send data to create/trigger actions+- `PUT` - Update existing resources+- `DELETE` - Remove resources+- `HEAD` - Like GET but without response body+- `OPTIONS` - Query supported methods+- `PATCH` - Partial resource updates+- `TRACE` - Echo request for debugging++**Common usage:**+- Health checks: `GET`+- API testing: `POST`, `PUT`, `DELETE`+- Webhook testing: `POST`++### Body++**Type:** String (optional)+**Available for:** `POST`, `PUT`, `PATCH` methods++The request body to send with the HTTP request. Supports both text and binary data.++**Text body examples:**+```json+{ "key": "value" }+```++**Binary data:**+For binary content (e.g., images), use base64 encoding with data URI:+```+data:image/jpeg;base64,/9j...+```++**Content type:** Set the appropriate `Content-Type` header (e.g., `application/json`, `application/octet-stream`).+### Headers++**Type:** Key-value pairs (optional)++Custom HTTP headers to include with your request.++**Common examples:**+```+Content-Type: application/json+Authorization: Bearer your_token_here+Accept: application/json+User-Agent: Custom-Agent/1.0+```++**Use cases:**+- **Authentication:** Send API tokens or credentials+- **Content negotiation:** Specify accepted response formats+- **Custom identification:** Add tracking or debugging headers++**Note:** openstatus automatically adds `User-Agent: openstatus/1.0` to all requests.++### Regions++**Type:** Array of Strings (required)+**Format:** Region identifiers (e.g., `iad`, `jnb`)++The geographical regions from which the HTTP request will be triggered. This allows for monitoring global availability and performance.++__Africa__++- Johannesburg, South Africa 🇿🇦 (free)++__Asia__++- Hong Kong, Hong Kong 🇭🇰 (free)+- Mumbai, India 🇮🇳+- Singapore, Singapore 🇸🇬+- Tokyo, Japan 🇯🇵++__Europe__++- Amsterdam, Netherlands 🇳🇱 (free)+- Bucharest, Romania 🇷🇴+- Frankfurt, Germany 🇩🇪+- London, United Kingdom 🇬🇧+- Madrid, Spain 🇪🇸+- Paris, France 🇫🇷+- Stockholm, Sweden 🇸🇪+- Warsaw, Poland 🇵🇱++__North America__++- Ashburn, Virginia, USA 🇺🇸 (free)+- Atlanta, Georgia, USA 🇺🇸+- Boston, Massachusetts, USA 🇺🇸+- Chicago, Illinois, USA 🇺🇸+- Dallas, Texas, USA 🇺🇸+- Denver, Colorado, USA 🇺🇸+- Guadalajara, Mexico 🇲🇽+- Los Angeles, California, USA 🇺🇸+- Miami, Florida, USA 🇺🇸+- Montreal, Canada 🇨🇦+- Phoenix, Arizona, USA 🇺🇸+- Queretaro, Mexico 🇲🇽+- Seattle, Washington, USA 🇺🇸+- San Jose, California, USA 🇺🇸+- Toronto, Canada 🇨🇦++__South America__++- Bogota, Colombia 🇨🇴+- Buenos Aires, Argentina 🇦🇷+- Rio de Janeiro, Brazil 🇧🇷+- Sao Paulo, Brazil 🇧🇷 (free)+- Santiago, Chile 🇨🇱++__Oceania__++- Sydney, Australia 🇦🇺 (free)++### Frequency++**Type:** String (required)+**Format:** Duration string (e.g., `30s`, `1m`, `1h`)++The interval at which the HTTP monitor will perform checks. Supported frequencies:+- `30 seconds`+- `1 minute`+- `5 minutes`+- `10 minutes`+- `30 minutes`+- `1 hour`++### Response Time Thresholds++#### Timeout++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for the HTTP request to complete. If the request exceeds this time, it is considered a failure.++#### Degraded++**Type:** Duration (optional)++The duration after which the HTTP request is considered to be performing in a degraded state. This threshold allows for proactive alerting on performance issues before a complete outage.++### Retry++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will automatically retry the HTTP request upon failure before reporting a definitive error. For example: `3`++### Assertions++Assertions allow you to validate specific aspects of the HTTP response.++#### Body Assertions++Validate the content of the HTTP response body.++**Comparisons:**+- `Contains`: The response body must include the specified string.+- `Not Contains`: The response body must not include the specified string.+- `Equal`: The response body must exactly match the specified string.+- `Not Equal`: The response body must not exactly match the specified string.+- `Empty`: The response body must be empty.++#### Status Code Assertions++Validate the HTTP status code of the response.++**Comparisons:**+- `Equal`: The status code must be exactly the specified value.+- `Not Equal`: The status code must not be the specified value.+- `Greater Than`: The status code must be greater than the specified value.+- `Greater Than or Equal`: The status code must be greater than or equal to the specified value.+- `Less Than`: The status code must be less than the specified value.+- `Less Than or Equal`: The status code must be less than or equal to the specified value.++#### Headers Assertions++Validate the presence or content of specific HTTP response headers.++**Purpose:** Verify cache headers, check security headers (e.g., `X-Frame-Options`), validate content-type.++**Comparisons:**+- `Contains`: A header's value must include the specified string.+- `Not Contains`: A header's value must not include the specified string.+- `Equal`: A header's value must exactly match the specified string.+- `Not Equal`: A header's value must not exactly match the specified string.+- `Empty`: A header's value must be empty or the header must not be present.++**Example Use Cases:**+- Verify `Cache-Control` headers are present and correct.+- Check for the existence of security-related headers like `Strict-Transport-Security`.+- Validate the `Content-Type` header in API responses.++### OpenTelemetry++Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.++#### OTLP Endpoint++**Type:** String (optional)+**Protocol:** HTTP only++The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported.++**Example:** `https://otlp.example.com/v1/metrics`++#### OTLP Headers++**Type:** Key-value pairs (optional)++Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.++**Common example:**+```+Authorization: Bearer <your_token>+```++### Public++**Type:** Boolean+**Default:** `false`++Controls the visibility of monitor data on your public status page.++- `true`: Monitor metrics and status are visible to all visitors of your status page.+- `false`: Monitor data remains private, accessible only within your openstatus dashboard.++**Use cases for public visibility:**+- Enhancing transparency with users regarding service health.+- Providing public API status pages.+- Displaying SaaS service availability to customers.++## Related resources++- **[Create Your First Monitor](/docs/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.+- **[CLI Reference](/docs/reference/cli-reference)** - Guide to managing openstatus monitors programmatically using the command-line interface.diff --git a/apps/web/src/content/pages/docs/reference/incident.mdx b/apps/web/src/content/pages/docs/reference/incident.mdxnew file mode 100644index 000000000..845a05996--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/incident.mdx@@ -0,0 +1,44 @@+---+category: Reference+title: Incident Reference+description: Technical specification for incident management and lifecycle+---++## Overview++An incident in openstatus represents a detected problem or service disruption related to a monitored resource. Incidents are automatically generated when a monitor reports a failure condition that meets predefined criteria. They serve as a central point for tracking, managing, and resolving service impairments.++**Key characteristics:**+- Automatically triggered by monitor failures.+- Aggregates related failure events for a single monitor.+- Provides a clear status of service health.++## Incident Triggering++An incident is triggered when a significant percentage of recent monitoring checks for a given monitor report a failed status. This mechanism prevents false positives from transient network issues.++**Trigger Condition:**+- **Failure Threshold:** An incident is initiated when at least 50% of the checks within a defined window (e.g., the last `N` checks or within a `T` duration) have reported a `failure` or `degraded` status.++## Incident Lifecycle and States++Incidents progress through several states reflecting their current resolution status. These states are managed through status reports (see [Status Report Reference](/docs/reference/status-report)).++**Primary States:**+- `investigating`: The incident has been detected, and the team is actively looking into the root cause.+- `identified`: The root cause of the incident has been identified.+- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.+- `resolved`: The incident has been fully resolved, and the service is operating normally.++## Properties++While an incident is active, it collects and displays key information related to the service disruption.++- **Monitor Association:** Each incident is directly linked to the monitor that triggered it, providing immediate context to the affected service.+- **Start Time:** Timestamp indicating when the incident was first detected and created.+- **Status Reports:** A chronological log of all updates and state changes applied to the incident.+- **Impacted Locations:** Details on the geographical regions from which the monitor reported failures.++## Related resources++- **[Status Report Reference](/docs/reference/status-report)** - Details on how incident statuses are managed and reported.diff --git a/apps/web/src/content/pages/docs/reference/location.mdx b/apps/web/src/content/pages/docs/reference/location.mdxnew file mode 100644index 000000000..db0c2fa42--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/location.mdx@@ -0,0 +1,62 @@+---+category: Reference+title: Location Reference+description: Complete technical specification for Location monitoring+---++## Overview++openstatus monitors your endpoints from multiple global locations to ensure accurate uptime and latency reporting. Locations span several infrastructure providers (Fly.io, Railway, and Koyeb), so IP availability varies: Fly.io regions expose both IPv4 and IPv6 addresses, Railway regions are IPv4-only, and Koyeb does not provide static IPs.++You can use these locations to:+- Configure region-specific checks+- Allowlist monitoring IPs in your firewall+- Understand where requests originate during synthetic monitoring++### Fly.io Regions & Monitoring IPs++Below is the complete list of regions used for monitoring, along with their associated IPv4 and IPv6 addresses.++| Region Code | Location Name | IPv4 Address | IPv6 Address |+|-------------|-------------------|-------------------|-------------------------------|+| ams | Amsterdam | 209.71.64.1 | 2a09:8280:e601:1:0:22:b79b:0 |+| arn | Stockholm | 209.71.98.189 | 2a09:8280:e602:1:0:22:b79b:0 |+| bom | Mumbai | 209.71.68.172 | 2a09:8280:e605:1:0:22:b79b:0 |+| cdg | Paris | 209.71.86.183 | 2a09:8280:e607:1:0:22:b79b:0 |+| dfw | Dallas | 209.71.71.89 | 2a09:8280:e609:1:0:22:b79b:0 |+| ewr | Newark | 209.71.69.221 | 2a09:8280:e610:1:0:22:b79b:0 |+| fra | Frankfurt | 209.71.90.204 | 2a09:8280:e612:1:0:22:b79b:0 |+| gru | São Paulo | 209.71.94.28 | 2a09:8280:e615:1:0:22:b79b:0 |+| iad | Washington, D.C. | 209.71.81.6 | 2a09:8280:e618:1:0:22:b79b:0 |+| jnb | Johannesburg | 209.71.83.120 | 2a09:8280:e620:1:0:22:b79b:0 |+| lax | Los Angeles | 209.71.91.96 | 2a09:8280:e621:1:0:22:b79b:0 |+| lhr | London | 209.71.85.82 | 2a09:8280:e622:1:0:22:b79b:0 |+| nrt | Tokyo | 209.71.88.150 | 2a09:8280:e625:1:0:22:b79b:0 |+| ord | Chicago | 209.71.89.1 | 2a09:8280:e626:1:0:22:b79b:0 |+| sin | Singapore | 209.71.80.112 | 2a09:8280:e632:1:0:22:b79b:0 |+| sjc | San Jose | 209.71.101.37 | 2a09:8280:e633:1:0:22:b79b:0 |+| syd | Sydney | 209.71.97.108 | 2a09:8280:e634:1:0:22:b79b:0 |+| yyz | Toronto | 209.71.99.51 | 2a09:8280:e637:1:0:22:b79b:0 |+++## Railway Regions & Monitoring IPs++Below is the complete list of Railway regions used for monitoring, along with their associated IPv4 addresses.++| Region Code | Location Name | IPv4 Address |+|--------------------------|------------------|-------------------|+| europe-west4-drams3a | Europe West | 208.77.244.15 |+| asia-southeast1-eqsg3a | Asia Southeast | 208.77.246.15 |+| us-east4-eqdc4a | US East | 162.220.234.15 |+| us-west2 | US West | 162.220.232.99 |++## Koyeb Regions & Monitoring IPs++Koyeb does not provide static IP addresses for their regions. For more information, please refer to Koyeb's [documentation](https://www.koyeb.com/docs/faqs/general#i-want-to-restrict-access-to-a-database-or-other-application-by-ip-address-what-ip-addresses-does-koyeb-use).++---++**Note:**++- Where available, IPv4 and IPv6 addresses are provided for allowlisting and diagnostics (Fly.io regions only; Railway is IPv4-only and Koyeb has no static IPs).+- Location names are for reference and may be used in the dashboard UI.diff --git a/apps/web/src/content/pages/docs/reference/maintenance.mdx b/apps/web/src/content/pages/docs/reference/maintenance.mdxnew file mode 100644index 000000000..01b9783a8--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/maintenance.mdx@@ -0,0 +1,91 @@+---+category: Reference+title: Maintenance Reference+description: Technical specification for scheduled maintenance windows in openstatus.+---++## Overview++A maintenance window is a scheduled period during which you expect planned disruption to one or more services — a database upgrade, a deployment, or infrastructure work. Announcing it ahead of time lets you communicate the disruption to your users instead of letting your status page register it as an unexpected outage.++A maintenance belongs to a single status page and targets one or more of that page's components — monitor-linked or static.++## Behavior++While a maintenance window is active (the current time is between `from` and `to`):++- The affected components display the **Under Maintenance** (info) status on the status page.+- A higher-priority event overrides it: an active incident (error) or an unresolved status report (degraded) takes precedence, so the component shows that status instead. Maintenance only outranks the default operational status.+- The maintenance is reflected in the historical status bars for the days it overlaps.++Maintenance windows **do not** exclude downtime from uptime calculations. The uptime percentage is computed from raw check results and is unaffected by maintenance windows; only the displayed status changes.++When a maintenance is created, status page subscribers can be notified that it has been scheduled (see [Notify](#notify)). Updating a maintenance never re-notifies.++## Configuration and Properties++### Title++**Type:** String (required)+**Length:** 1–256 characters++A short, human-readable name for the maintenance window.++**Example:** `"Database Upgrade"`++### Message++**Type:** String (required)++A description of the maintenance shown to users, explaining what is happening and the expected impact.++**Example:** `"Upgrading our database to improve performance. Brief interruptions may occur."`++### From++**Type:** Datetime (required)+**Format:** RFC 3339 / ISO 8601 (e.g., `2026-01-20T02:00:00Z`)++When the maintenance window starts.++### To++**Type:** Datetime (required)+**Format:** RFC 3339 / ISO 8601 (e.g., `2026-01-20T04:00:00Z`)++When the maintenance window ends. Must be later than `from`.++### Status Page++**Type:** Integer (required)++The id of the status page this maintenance belongs to. A maintenance is scoped to exactly one status page.++### Affected Components++**Type:** Array of integers (optional)+**Default:** `[]`++The ids of the page components that should display the Under Maintenance status during the window. Each component must belong to the status page referenced above, and can be either a monitor-linked or a static component.++In the v1 REST API these are passed as `monitorIds`, which accepts monitor components only and is retained for backward compatibility. Static components can be targeted through the dashboard.++### Notify++**Type:** Boolean (optional)+**Default:** `false`++A one-time flag evaluated at creation time — it is **not** stored on the maintenance record and cannot be read back. When set, status page subscribers are notified that the maintenance has been scheduled.++The v1 REST API does not expose this flag; it notifies subscribers automatically when a maintenance is created on a page whose workspace has subscribers enabled.++## Relationships++- **Status page** — a maintenance is tied to a single page. Deleting the page deletes its maintenance windows.+- **Page components** — a maintenance can affect multiple components (monitor-linked or static), and a component can be covered by multiple (including overlapping) maintenance windows.++## Related resources++- **[Status Page Reference](/docs/reference/status-page)** - How maintenance windows surface on the public status page.+- **[Page Components](/docs/reference/page-components)** - The monitor and static components a maintenance window can target.+- **[Status Report Reference](/docs/reference/status-report)** - Communicate unplanned incidents, as opposed to scheduled maintenance.diff --git a/apps/web/src/content/pages/docs/reference/mcp-server.mdx b/apps/web/src/content/pages/docs/reference/mcp-server.mdxnew file mode 100644index 000000000..55bee02c7--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/mcp-server.mdx@@ -0,0 +1,193 @@+---+category: Reference+title: MCP Server+description: Connect openstatus to AI assistants via the Model Context Protocol+---++The openstatus MCP server lets AI assistants (Claude Desktop, Cursor, and other [Model Context Protocol](https://modelcontextprotocol.io) clients) read and manage your status pages, status reports, and maintenance windows directly from a conversation.++## Endpoint++```+https://api.openstatus.dev/mcp+```++The transport is **Streamable HTTP** (stateless). The server speaks JSON-RPC 2.0 over a single endpoint that accepts `GET`, `POST`, and `DELETE`.++## Authentication++Every request must include your openstatus API key in the `x-openstatus-key` header — the same key REST and ConnectRPC use. There is no separate MCP-only credential.++```http+x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+```++Get a key from the dashboard's **Settings → API Tokens**.++### Scopes++Each API key carries a scope that controls what tools the MCP server exposes:++- **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.++For AI agents that should only observe state — health summaries, paging on-call, drafting communication — issue a **Read-only** key. The server gates writes at two layers (the `tools/list` filter is the visible UX; the service-layer scope check is the boundary), so a misconfigured client can't accidentally mutate.++## Tools++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_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`. |+| `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. |++### 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.++### Notifying subscribers++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.++`notified: true` means the dispatch call returned without throwing — **not** that every subscriber received a message. If the workspace plan doesn't include subscriber notifications, the service is a silent no-op and the response will still report `notified: true`. Treat the field as "the dispatch ran cleanly," not as a delivery receipt.++| Tool | What `notify: true` sends |+|----------------------------|---------------------------|+| `create_status_report` | Notification for the initial update |+| `add_status_report_update` | Notification for the new update |+| `resolve_status_report` | Resolution notification |+| `create_maintenance` | Maintenance scheduled notification |+| `update_status_report` | n/a — metadata-only edit, never has a notify path |++The required `notify` field, combined with the mandatory draft-and-confirm workflow in each tool's description, encodes the contract that LLMs must:++1. Draft the title/status/message/components.+2. Show the draft to the user.+3. Ask **explicitly** whether to notify subscribers.+4. Only call the tool once both content and notify are confirmed.++The tool's response includes a `notified: boolean` field so the assistant can confirm what actually went out. If the workspace plan doesn't include subscriber notifications, `notify: true` is a no-op inside the service (no error, just nothing dispatched).++### Lookup-before-mutate++`create_status_report` and `create_maintenance` require a `pageId`, and they (plus `update_status_report`) accept an optional `pageComponentIds`. The tool descriptions instruct the model to call `list_status_pages` for the `pageId` and `list_page_components` for component ids first; **never** type a numeric id you don't know — make the assistant resolve it. Ids that don't belong to the workspace (or, for components, to the supplied page) come back as `NOT_FOUND`.++## Configure Claude Desktop++Claude Desktop launches MCP servers as local stdio processes, so the remote HTTP server is bridged through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) — a small open-source proxy that translates Claude Desktop's stdio calls into HTTP requests against `https://api.openstatus.dev/mcp`. You'll need Node.js 18+ on your PATH so Claude Desktop can run `npx`.++Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):++```json+{+ "mcpServers": {+ "openstatus": {+ "command": "npx",+ "args": [+ "mcp-remote",+ "https://api.openstatus.dev/mcp",+ "--header",+ "x-openstatus-key: ${API_KEY}"+ ],+ "env": {+ "API_KEY": "os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"+ }+ }+ }+}+```++The API key is held in `env` and referenced via `${API_KEY}` in the `--header` value because `mcp-remote` parses header args before shell expansion — inlining the key after the colon breaks parsing.++Fully quit and relaunch Claude Desktop (`Cmd+Q` on macOS, **File → Quit** on Windows). The openstatus tools appear in the tool picker after restart.++## Configure Cursor++In Cursor, open **Settings → MCP → Add Server**:++```json+{+ "openstatus": {+ "type": "http",+ "url": "https://api.openstatus.dev/mcp",+ "headers": {+ "x-openstatus-key": "os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"+ }+ }+}+```++## Errors++Errors map by severity:++- **Recoverable** (`NOT_FOUND`, `VALIDATION`, `CONFLICT`, `LIMIT_EXCEEDED`) come back as a tool result with `isError: true`. The model can read the message and retry with corrected input.+- **Transport-level** (`UNAUTHORIZED`, `FORBIDDEN`, `INTERNAL`, malformed input) come back as a JSON-RPC error.++Error messages are not redacted — the consumer is an LLM that benefits from the detail.++## 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++Every mutation invoked through MCP appears in the workspace audit log with:++- `actor_type = "mcp"` — slice by surface: `WHERE actor_type = 'mcp'`.+- `actor_id` = the API key's stable identifier (not the workspace id) — trace a specific key with `WHERE actor_id = '<keyId>'`.+- `actor_user_id` = the openstatus user who created the API key (custom keys only) — attribute mutations back to a person with a join to the `user` table.diff --git a/apps/web/src/content/pages/docs/reference/notification.mdx b/apps/web/src/content/pages/docs/reference/notification.mdxnew file mode 100644index 000000000..c55a6b430--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/notification.mdx@@ -0,0 +1,172 @@+---+category: Reference+title: Notification Channels Reference+description: Technical specification for openstatus notification channels and alert payloads.+---++## Overview++Notifications in openstatus provide real-time alerts regarding changes in monitor status, such as recovery from an outage or detection of a new failure. By default, no notification channels are configured in a new workspace. Users must configure and enable specific channels to receive alerts.++## Notification Channels++Each notification channel requires specific configuration parameters to enable alert delivery.++### Slack++Integrates with Slack to send alerts to a designated channel.++**Configuration:**+- **Incoming Webhook URL:** (Required) A [Slack incoming webhook URL](https://api.slack.com/incoming-webhooks) where notifications will be posted.+ **Example**: `https://hooks.slack.com/services/XXX/YYY/ZZZ`++You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) to add a custom logo.+++Sends alerts directly to a specified email address.++**Configuration:**+- **Email Address:** (Required) The recipient's email address.++### Discord++Delivers alerts to a Discord channel via a webhook.++**Configuration:**+- **Webhook URL:** (Required) A [Discord webhook URL](https://support.discord.com/hc/en-us/articles/228383668) for the target channel.+ **Example:** `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`++You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) to add a custom logo.++### Grafana OnCall IRM++Sends notifications to a Grafana OnCall IRM.++**Configuration:**+- **Webhook URL:** (Required) A [Grafana OnCall IRM webhook URL](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/webhooks/incoming-webhooks/oncall-webhooks/).+++### Google Chat++Sends notifications to a Google Chat space.++**Configuration:**+- **Webhook URL:** (Required) A [Google Chat webhook URL](https://developers.google.com/workspace/chat/quickstart/webhooks) for the target space.++### SMS++Sends alerts as SMS messages to a mobile phone number.++**Configuration:**+- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).++**Note:** SMS delivery can vary by country due to provider routing. Contact support if delivery issues are encountered. WhatsApp notifications may be an alternative.+++Sends alerts as WhatsApp messages to a mobile phone number.++**Configuration:**+- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).++### Telegram++Delivers alerts to a specified Telegram chat.++**Configuration:**+- **Chat ID:** (Required) The unique identifier for the Telegram chat. This typically requires manual retrieval; users can ask `@raw_info_bot` for their chat ID.++**Bot ID:** The official openstatus Telegram bot ID is `@openstatushq_bot`.++### Webhook++Sends HTTP POST requests to a custom endpoint with a JSON payload.++**Configuration:**+- **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 Payload++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+{+ "monitor": {+ "id": 1,+ "name": "test",+ "url": "http://openstat.us"+ },+ "cronTimestamp": 1744023705307,+ "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` | 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. |++#### Authentication++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++The validation schema for webhook payloads:++```ts+import { z } from "zod";++export const PayloadSchema = z.object({+ monitor: z.object({+ id: z.number(),+ name: z.string(),+ url: z.string(),+ }),+ cronTimestamp: z.number(),+ status: z.enum(["degraded", "error", "recovered"]),+ statusCode: z.number().optional(),+ latency: z.number().optional(),+ errorMessage: z.string().optional(),+});+```++### OpsGenie++Integrates with OpsGenie for incident management.++**Configuration:**+- **API Key:** (Required) An API key obtained from your OpsGenie account.++### PagerDuty++Integrates with PagerDuty for incident alerting.++**Configuration:**+- **Integration Steps:** (Required) Follow the specific integration steps provided within the PagerDuty workflow to set up this channel.++### Ntfy++Sends notifications to an Ntfy topic.++**Configuration:**+- **Ntfy Topic:** (Required) The topic name to which notifications will be published.+- **Custom Server URL:** (Optional) The URL of a custom Ntfy server if not using the default.+- **Bearer Token:** (Optional) An authentication token for accessing the Ntfy server.++## Related resources++- **[Incident Reference](/docs/reference/incident)** - Information about incident creation and management.diff --git a/apps/web/src/content/pages/docs/reference/page-components.mdx b/apps/web/src/content/pages/docs/reference/page-components.mdxnew file mode 100644index 000000000..2a07c5248--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/page-components.mdx@@ -0,0 +1,304 @@+---+category: Reference+title: Page Components Reference+description: Complete specification for openstatus page components on status pages.+---+++## Overview++Page components are the individual elements displayed on your status page that show the operational status of your services. They provide a flexible way to organize and present both monitored services and static content on your status page.++**Key features:**+- Support for both monitor-linked and static components.+- Organize components into logical groups.+- Custom ordering and arrangement.+- Individual status tracking with incidents, reports, and maintenances.+- Granular control over what appears on your status page.++## Component Types++Page components come in two distinct types, each serving different purposes on your status page.++### Monitor Components++**Type:** `monitor`++Monitor components are linked to an active monitor in your workspace. They automatically inherit the monitor's status and display real-time health information.++**Characteristics:**+- Display live monitor status (up, degraded, down).+- Show active incidents from the linked monitor.+- Include historical uptime data.+- Reflect the monitor's current operational state.+- Automatically update when the monitor changes.++**Use cases:**+- Displaying API endpoint health.+- Showing website availability.+- Tracking critical service dependencies.+- Monitoring infrastructure components.++#### Configuring Monitor Components++When you create a monitor component, you link it to an existing monitor in your workspace. This connection provides several benefits:++**Automatic incident tracking:**+When your monitor detects a failure (connection timeout, HTTP error, assertion failure), an incident is automatically created and displayed on the status page. The component will show an **error** status until the monitor recovers.++**Real-time status updates:**+The component reflects the current operational state of your monitor. If the monitor is actively checking and healthy, your visitors see a **success** status. If checks fail, they immediately see the issue.++**Historical data visualization:**+Monitor components display historical uptime data through status trackers. Depending on your [tracker configuration](/docs/tutorial/how-to-configure-status-page#1-tracker-configuration), you can show:+- **Absolute bar with duration card**: Shows the time spent in each status (success, error, degraded, maintenance).+- **Absolute bar with request card**: Shows the number of successful vs. failed requests.+- **Manual bar**: Shows only the most significant status of each day.++**Uptime calculations:**+Monitor components calculate uptime percentages based on:+- Duration of successful vs. failed checks (for duration-based tracking).+- Number of successful vs. failed requests (for request-based tracking).+- Includes incidents and status reports in the calculation.++**Monitor selection:**+When adding a monitor component, the dashboard shows you available monitors with indicators for:+- **Public/Private status**: Whether the monitor is already public.+- **Active status**: Only active monitors can be linked.+- **Already linked**: Monitors already used on this status page are unavailable.++<Aside type="tip">+You can customize the component name to be different from the monitor name. For example, your monitor might be named "prod-api-health-check" internally, but the component can display as "API Server" for your visitors.+</Aside>++**Status hierarchy:**+1. **Error** - Active incidents from the linked monitor.+2. **Degraded** - Unresolved status reports affecting this component.+3. **Info** - Ongoing scheduled maintenance.+4. **Success** - Healthy and operational.++**What affects monitor components:**+- ✅ Automatic incidents (from monitor failures)+- ✅ Manual status reports+- ✅ Scheduled maintenances++### Static Components++**Type:** `static`++Static components are independent elements not linked to any monitor. They allow you to display services or systems that you manually manage through status reports and maintenance windows only.++**Characteristics:**+- No automatic status updates.+- Status controlled exclusively by manual status reports and scheduled maintenances.+- Useful for third-party services or manual tracking.+- Do not display incidents (no automatic incident creation).+- Provide flexibility for non-monitored services.++**Use cases:**+- Third-party service dependencies (e.g., payment providers like Stripe, email services like SendGrid).+- Manual status tracking for systems without monitors.+- Services monitored through external tools.+- Components that only need maintenance window communication.+- Legacy systems without API endpoints to monitor.++<Aside type="caution">+Static components **only** respond to manual status reports and scheduled maintenances. They never automatically detect issues or create incidents. If you need automatic failure detection, use a monitor component instead.+</Aside>++#### Managing Static Components++Static components give you full manual control over what your visitors see:++**Status reports:**+Create status reports to indicate issues or degraded performance for static components. For example:+- "Stripe payment processing experiencing delays" (degraded status).+- "Email delivery service partially unavailable" (degraded status).++Once you resolve the issue and mark the status report as resolved, the component returns to a success status.++**Maintenance windows:**+Schedule maintenance windows to inform visitors about planned downtime:+- "Scheduled database backup - Sunday 2:00 AM - 4:00 AM" (info status).+- "Third-party CDN maintenance window" (info status).++During the maintenance window, the component shows an info status. After the window ends, it returns to its previous status.++**No automatic monitoring:**+Static components do not perform any health checks or generate incidents. You are responsible for:+- Monitoring the service through other means.+- Creating status reports when issues occur.+- Updating reports when issues are resolved.+- Communicating maintenance windows in advance.++**Status hierarchy:**+1. **Degraded** - Unresolved status reports affecting this component.+2. **Info** - Ongoing scheduled maintenance.+3. **Success** - No active reports or maintenances.++**What affects static components:**+- ✅ Manual status reports+- ✅ Scheduled maintenances+- ❌ Automatic incidents (not supported)++## Component Groups++Component groups allow you to organize related page components into logical sections on your status page. Groups improve readability and help visitors understand your service architecture.++**Benefits:**+- Visual organization of related services.+- Collapsible sections for better page structure.+- Independent ordering within groups.+- Clear service categorization.++**Examples of grouping strategies:**++| Group Name | Components |+|------------|------------|+| **API Services** | Authentication API, Data API, WebSocket API |+| **Infrastructure** | Database, Cache, Message Queue |+| **External Dependencies** | Payment Provider, Email Service, CDN |+| **Regional Services** | US Region, EU Region, APAC Region |++**Group configuration:**+- **Name:** The group heading displayed on your status page.+- **Order:** Position of the group relative to other groups and ungrouped components.+- **Components:** The page components contained within this group.+## Events and Status++Page components can be affected by up to three types of events that influence their displayed status. The type of component determines which events apply:++| Event Type | Monitor Components | Static Components |+|------------|-------------------|-------------------|+| **Incidents** | ✅ Automatic | ❌ Not supported |+| **Status Reports** | ✅ Manual | ✅ Manual |+| **Maintenances** | ✅ Manual | ✅ Manual |++### Incidents++**Applies to:** Monitor components only++Incidents are automatically generated when a monitor detects a failure. They represent unplanned outages or degraded performance discovered through active monitoring.++**How incidents are created:**+- Monitor check fails (connection timeout, HTTP error, DNS failure).+- Monitor assertion fails (wrong status code, unexpected response body).+- Monitor reaches degraded threshold (response time too slow).++**Status impact:** Components with active incidents show an **error** status. This takes the highest priority in the status hierarchy.++**Resolution:** Incidents are automatically resolved when the monitor recovers and checks succeed again.++<Aside>+Static components **never** generate incidents because they are not linked to monitors. Use status reports for manual issue tracking on static components.+</Aside>++### Status Reports++**Applies to:** Both monitor and static components++Status reports are manually created updates about component health or issues. They provide a way to communicate problems that may not trigger automatic monitoring or to manually report issues with static components.++**Status impact:** Components with unresolved status reports show a **degraded** status (unless overridden by an incident for monitor components).++**Use cases for monitor components:**+- Reporting known issues that don't cause complete outages.+- Communicating performance degradation not captured by monitoring.+- Providing context for intermittent issues.++**Use cases for static components:**+- Reporting third-party service issues (e.g., "Stripe processing delays").+- Communicating external service degradation.+- Announcing partial outages of non-monitored systems.++**Attaching to components:** When creating a status report, you can select which components are affected. Multiple components can be attached to a single report.++### Maintenances++**Applies to:** Both monitor and static components++Maintenances are scheduled maintenance windows that you create in advance. They inform visitors about planned downtime or service interruptions for both monitored and static components.++**Status impact:** Components with ongoing maintenances show an **info** status (unless overridden by incidents or reports).++**Use cases for monitor components:**+- Scheduled system upgrades that will cause downtime.+- Infrastructure changes that affect monitored services.+- Planned deployments requiring service restarts.++**Use cases for static components:**+- Third-party maintenance windows (e.g., "Payment provider scheduled maintenance").+- External service upgrade notifications.+- Planned downtime for non-monitored dependencies.++**Scheduling:** Maintenances have a defined start and end time. The info status automatically appears during the window and disappears when the maintenance ends.++**Attaching to components:** When creating a maintenance, you select which components will be affected. This allows you to communicate maintenance impact across multiple services.++## Managing Components++### Adding Components++You can add components to your status page in two ways:++1. **Individual components:** Add a single component outside of any group.+2. **Components within groups:** Add a component directly into a new or existing group.++When adding a monitor component, you can only select from monitors that:+- Are currently active.+- Have not been deleted.+- Are not already linked to another component on this status page.++### Reordering Components++Components and groups can be reordered using drag-and-drop functionality in the dashboard. The order determines how they appear on your status page from top to bottom.++**Ordering tips:**+- Place your most critical services at the top.+- Group related services together.+- Consider visitor priorities when ordering.++### Editing Components++You can modify the following properties of existing components:+- Component name and description.+- Group assignment (move between groups or make ungrouped).+- Display order.++**Note:** You cannot change a component's type (monitor to static or vice versa) after creation. To change types, delete the component and create a new one.++### Deleting Components++When you delete a component, any associations with status reports and maintenances are automatically removed. The linked monitor (if applicable) is not deleted and remains available in your workspace.++**Warning:** Deletion is permanent and cannot be undone. Ensure you want to remove the component before confirming deletion.++## Deprecation Notice++The legacy monitor-only system for status pages is deprecated in favor of the more flexible page component system.++**Deprecated approach:**+- Status pages directly referenced monitors.+- No support for static content.+- Limited organizational flexibility.++**Current approach (page components):**+- Status pages contain page components.+- Components can be monitors or static content.+- Full support for grouping and custom ordering.+- Better separation between monitoring and status page presentation.++### API Compatibility++**v1 API (backward compatibility):**+The v1 API continues to display `monitorIds` and `monitors` fields in status page responses to avoid breaking changes for existing integrations. However, these fields now only include page components that are explicitly of type `monitor`. Static components are not included in these legacy fields.++**Future API versions:**+Newer API versions will primarily use the `pageComponents` structure. The legacy `monitors` and `monitorIds` fields will be removed in future API versions. We recommend migrating your integrations to use `pageComponents` for full feature support.++## Related resources++- **[Status Page Reference](/docs/reference/status-page)** - Complete status page configuration reference.+- **[Status Report Reference](/docs/reference/status-report)** - Details on creating and managing status reports.+- **[Create Status Page](/docs/tutorial/how-to-create-status-page)** - Step-by-step tutorial on creating a status page.+- **[HTTP Monitor Reference](/docs/reference/http-monitor)** - Technical specification for HTTP monitors that can be linked to components.diff --git a/apps/web/src/content/pages/docs/reference/private-location.mdx b/apps/web/src/content/pages/docs/reference/private-location.mdxnew file mode 100644index 000000000..a7be3cde2--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/private-location.mdx@@ -0,0 +1,54 @@+---+category: Reference+title: Private Location Reference+description: Technical specification for configuring and utilizing private monitoring locations.+---++## Overview++A private location in openstatus enables users to deploy monitoring probes within their own infrastructure or private networks. This capability is essential for monitoring internal services, APIs, or systems that are not publicly accessible from the internet, such as those behind firewalls or within a Virtual Private Cloud (VPC).++**Key benefits:**+- **Internal Monitoring:** Monitor services running on private networks.+- **Security:** Keep sensitive internal endpoints protected from public exposure.+- **Compliance:** Meet specific regulatory or security compliance requirements by controlling data paths.+- **Reduced Latency:** Conduct checks closer to your services for more accurate performance metrics.++## How it Works++When a private location is configured, openstatus provides a mechanism (e.g., a container image or agent) that you deploy within your private environment. This deployed component acts as a local monitoring probe, executing checks on behalf of your openstatus account.++1. **Deployment:** You deploy the openstatus private probe within your chosen infrastructure (e.g., a Docker container on a server, a Kubernetes pod).+2. **Secure Connection:** The private probe establishes a secure, outbound-only connection to the openstatus platform, eliminating the need for inbound firewall rules.+3. **Check Execution:** openstatus dispatches monitoring tasks to your private probe via this secure connection. The probe then executes the configured checks against your internal services.+4. **Result Reporting:** The private probe securely sends the monitoring results (e.g., status, latency, response data) back to the openstatus platform for processing, alerting, and visualization.++## Configuration++Detailed steps for setting up a private location involve:++1. **Probe Deployment:** Provisioning a server or container environment within your private network.+2. **Agent Installation:** Deploying the openstatus private probe agent (e.g., Docker image) onto your infrastructure.+3. **Authentication:** Configuring the probe with necessary API keys or tokens to securely authenticate with your openstatus workspace.+4. **Network Access:** Ensuring the deployed probe has network access to the internal services it needs to monitor, as well as outbound access to the openstatus platform.++## Current API surface++Private locations can currently be created, listed, updated, and deleted from the authenticated dashboard API. The supported private location fields are:++- `name`: the display name shown in the dashboard.+- `token`: the probe authentication token.+- `monitors`: the monitor IDs attached to the private location.+- `lastSeenAt`: the last time the private location probe connected.++Additional display metadata such as country, city, or hosting provider is not currently part of the private location model. If you need that information today, include it in the location name, for example `Frankfurt - Hetzner`.++**Example Use Cases:**+- Monitoring an internal REST API that is only accessible from within your corporate network.+- Checking the health of a database server running on a private subnet.+- Performing synthetic transactions on an internal web application before it's exposed publicly.++## Related resources++- **[How to Deploy Probes on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - A guide for deploying private probes using Cloudflare Workers/Containers. (Example deployment guide)+- **[CLI Reference](/docs/reference/cli-reference)** - Manage monitors as code, including those utilizing private locations.diff --git a/apps/web/src/content/pages/docs/reference/status-page.mdx b/apps/web/src/content/pages/docs/reference/status-page.mdxnew file mode 100644index 000000000..2d7aa2da4--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/status-page.mdx@@ -0,0 +1,143 @@+---+category: Reference+title: Status Page Reference+description: Complete technical specification for openstatus status page configuration.+---++## Overview++A status page is a dedicated web interface provided by openstatus that publicly displays the operational status of your services and systems. It serves as a transparent communication tool during incidents and for showcasing overall service health.++**Key features:**+- Real-time service status updates.+- Incident communication and history.+- Customizable branding and domain.+- Multiple access control options.+- Multi-language support with a locale switcher.++## Configuration++openstatus provides several configuration options to customize your status page's appearance, accessibility, and functionality.++### Slug++**Type:** String (required)+**Format:** URL-friendly string (e.g., `my-service-status`)++A unique identifier that forms part of your status page's default URL. For example, a slug of `status` will result in a URL like `https://status.openstatus.dev`.++### Custom Domain++**Type:** String (optional)+**Format:** Valid domain name (e.g., `status.example.com`)++Allows you to host your status page on a custom domain. Once configured, your status page will be accessible at `https://your-custom-domain.com`.++**DNS Configuration:**++| Domain type | Record | Name | Value | TTL |+|---|---|---|---|---|+| Subdomain (e.g., `status.example.com`) | CNAME | `status` | `cname.vercel-dns.com` | 86400 |+| Apex domain (e.g., `example.com`) | A | `@` | `76.76.21.21` | 86400 |++**Domain verification (conditional):** If your domain is already registered on another Vercel project, a TXT record will be required to prove ownership. The dashboard will display the exact TXT record name and value when this step is needed.++After saving your custom domain in the dashboard, the exact DNS records will be displayed with any additional verification steps needed.++### Password (Basic Auth)++**Type:** String (optional)++Enables basic password protection for your status page. If a password is set, users will be redirected to a login page (`/login`) to gain access. The password is stored in a cookie upon successful authentication.++**Sharing with password:** You can provide direct access by appending the password as a URL search parameter: `https://[slug].openstatus.dev/?pw=your-secret-password`. This method is also useful for authenticating private RSS feeds.++### Magic Link (Session Auth)++**Type:** Boolean (add-on feature)++Restricts access to your status page to users with approved email domains. Users receive a magic link via email, which, upon clicking, authenticates them via a session token. This feature is typically available as a paid add-on for specific plans.++### IP Restriction (Network Auth)++**Type:** String (add-on feature)++Restricts access to your status page based on client IPv4 addresses. You provide a comma-separated list of CIDR ranges (e.g., `192.168.1.0/24, 10.0.0.0/8`), and only requests from those networks can view the page. Single IPs without a subnet mask are treated as `/32`.++Visitors from outside the allowed ranges are redirected to a static "Access Restricted" page — there is no login flow since IP-based access cannot be changed by the user.++**Configuration:**+- Set `access_type` to `ip-restriction` in the dashboard or API.+- Provide `allowed_ip_ranges` as a comma-separated list of IPv4 CIDR ranges (we automatically+ append /32 to single IPs).+- IPv6 is not supported++**Note:** This feature is available as a paid add-on for Starter and Pro plans.++### Favicon++**Type:** Image file (`.ico`, `.png`, `.svg`)++Allows you to upload a custom favicon that will appear in browser tabs and bookmarks for your status page. SVG files are sanitized server-side and must be under 100KB.++### JSON Feed++**Type:** Read-only endpoint+**Format:** JSON++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.++**Example:** `https://status.openstatus.dev/feed/json`++**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.+- **`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.++These deprecated fields are currently maintained for backward compatibility but may be removed in future versions.++### SSH Command++**Type:** Command-line utility++Allows you to quickly check the current status page status directly from your terminal using an SSH command.++**Usage:**++```bash+ssh [slug]@ssh.openstatus.dev+```++**Example:** `ssh [email protected]`++### Translations (i18n)++**Type:** Per-page configuration (paid plans only)++Enables multi-language support for your status page. You can set a default locale and optionally enable a locale switcher so visitors can choose their preferred language.++**Supported locales:** `en` (English), `fr` (Français), `de` (Deutsch)++**Configuration:**+- **Default Locale** — the fallback language for your status page (defaults to `en`).+- **Locale Switcher** — when enabled, visitors see a language dropdown. You select which locales to offer.++**Routing:** The default locale is omitted from the URL (`as-needed` prefix). Non-default locales appear in the path (e.g., `/fr/events`).++See [How to translate your status page](/docs/guides/how-to-translate-status-page) for setup instructions and contributing new translations.++### White Label++**Type:** Boolean (add-on feature)++Removes the "powered by openstatus.dev" footer from your status page, providing a fully branded experience. This feature is typically available as a paid add-on for Starter and Pro plans and is enabled via your workspace settings, affecting all status pages within that workspace.++## Related resources++- **[Create Status Page](/docs/tutorial/how-to-create-status-page)** - Step-by-step tutorial on creating a status page.+- **[How to Configure Status Page](/docs/tutorial/how-to-configure-status-page)** - Guide on advanced status page configuration.+- **[Status Report Reference](/docs/reference/status-report)** - Details on how incident statuses are managed and reported.+- **[How to Translate Your Status Page](/docs/guides/how-to-translate-status-page)** - Enable multiple languages and contribute translations.diff --git a/apps/web/src/content/pages/docs/reference/status-report.mdx b/apps/web/src/content/pages/docs/reference/status-report.mdxnew file mode 100644index 000000000..fdc665f97--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/status-report.mdx@@ -0,0 +1,57 @@+---+category: Reference+title: Status Report Reference+description: Technical specification for incident status updates within openstatus.+---++## Overview++A status report is a chronological update or event associated with an ongoing incident in openstatus. These reports are crucial for communicating the progress of an incident, from initial detection to final resolution, providing transparency to stakeholders.++**Purpose:**+- To document the lifecycle and progress of an incident.+- To communicate current incident status and actions taken.+- To provide historical context for post-incident analysis.++## Relationship to Incidents++Each status report is directly linked to a specific incident. As an incident progresses through its resolution process, new status reports are added to provide updates, often accompanied by a change in the incident's overall status.++## Configuration and Properties++A status report consists of several key properties that define its content and context.++### Status++**Type:** Enumerated String (required)++Represents the current stage or state of the associated incident at the time the report is issued. The available statuses are:++- `investigating`: The incident has been detected, and the team is actively looking into the root cause.+- `identified`: The root cause of the incident has been identified.+- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.+- `resolved`: The incident has been fully resolved, and the service is operating normally.++### Date++**Type:** Datetime (required)+**Format:** ISO 8601 (e.g., `2026-01-05T12:30:00Z`)++The timestamp indicating when the status report was created or when the reported status took effect. This provides a clear timeline for incident progression.++### Message++**Type:** String (required)++A descriptive message detailing the update, actions taken, or any relevant information regarding the incident at the time of the report. This message should be clear and concise, providing context to the status change.++**Example Messages:**+- `"Initial detection of elevated error rates on the API. Investigating potential upstream issues."`+- `"Root cause identified as a misconfigured caching layer. Working on a rollback."`+- `"Fix deployed to production. Monitoring service health for full recovery."`+- `"All services restored to normal operation. Incident resolved."`++## Related resources++- **[Incident Reference](/docs/reference/incident)** - Detailed information on incident creation and lifecycle.+- **[Status Page Reference](/docs/reference/status-page)** - Information on how status reports are displayed on public status pages.diff --git a/apps/web/src/content/pages/docs/reference/subscriber.mdx b/apps/web/src/content/pages/docs/reference/subscriber.mdxnew file mode 100644index 000000000..def6a3ac4--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/subscriber.mdx@@ -0,0 +1,45 @@+---+category: Reference+title: Subscriber Reference+description: Technical specification for managing status page subscribers and their notifications.+---++## Overview++A subscriber in openstatus is an entity (typically a user or an integration) that opts to receive real-time notifications and updates regarding incidents and status changes on a specific status page. Subscribers play a crucial role in maintaining transparent communication during service disruptions.++**Key functions of subscribers:**+- Receive automated alerts when monitor statuses change or incidents are updated.+- Stay informed about service health without actively monitoring the status page.+- Choose preferred notification channels for receiving updates.++## Subscription Process++Users typically subscribe to a status page's updates through a dedicated interface provided on the status page itself. The process involves:++1. **Inputting Contact Information:** Providing an email address, phone number, or other contact details depending on the available notification channels.+2. **Opt-in Confirmation:** Confirming their subscription, often through a verification link sent to the provided contact to prevent unwanted subscriptions.+3. **Channel Selection (Optional):** Selecting which specific notification channels (e.g., email, SMS, Slack webhook) they wish to receive updates through, if multiple options are available.++## Notification Types Received++Subscribers receive notifications for key events affecting the monitored services linked to the status page:++- **Incident Creation:** When a new incident is detected and published.+- **Incident Updates:** When status reports are published for an ongoing incident (e.g., status changes from `investigating` to `identified`, `monitoring`, or `resolved`).+- **Monitor Status Changes:** Direct alerts for individual monitor status changes if configured to do so (less common for public subscribers).+- **Scheduled Maintenance:** When a maintenance window is created on the page, subscribers can be notified that it has been scheduled (see the [Maintenance Reference](/docs/reference/maintenance)).++## Subscriber Management++Status page administrators can manage their subscriber lists, including:++- **Viewing Subscribers:** Accessing a list of all active subscribers for a status page.+- **Adding/Removing Subscribers:** Manually adding or removing subscribers.+- **Communication:** Sending ad-hoc notifications to the subscriber list (if supported by the platform).++## Related resources++- **[Status Page Reference](/docs/reference/status-page)** - Detailed information on managing and configuring status pages.+- **[Notification Channels Reference](/docs/reference/notification)** - Technical specifications for the various notification delivery methods.+- **[Incident Reference](/docs/reference/incident)** - Information about incident creation and management.diff --git a/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx b/apps/web/src/content/pages/docs/reference/tcp-monitor.mdxnew file mode 100644index 000000000..10224af0d--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx@@ -0,0 +1,150 @@+---+category: Reference+title: TCP Monitor Reference+description: Complete technical specification for TCP service monitoring.+---++## Overview++A TCP Monitor is a component that establishes a connection to a specified TCP endpoint (IP address and port) to verify its reachability and responsiveness. This is fundamental for monitoring the availability of services that communicate over TCP, such as databases, mail servers, and custom network services.++**Use cases:**+- Database server availability checks (e.g., PostgreSQL, MySQL).+- Mail server (SMTP, IMAP, POP3) reachability.+- Custom application service port monitoring.+- Validating network connectivity to specific endpoints.++## Configuration++### URI++**Type:** String (required)+**Format:** Hostname or IP address with port (e.g., `example.com:8080`, `192.168.1.1:22`)++The endpoint of the TCP service you want to monitor. This includes the hostname or IP address and the port number.++**Examples:**+- `openstat.us:443`+- `db.internal:5432`+- `10.0.0.5:3306`++### Regions++**Type:** Array of Strings (required)+**Format:** Region identifiers (e.g., `iad`, `jnb`)++The geographical regions from which the TCP connection attempt will be initiated. This allows for verification of service availability and network latency across different global locations.++__Africa__++- Johannesburg, South Africa 🇿🇦 (free)++__Asia__++- Hong Kong, Hong Kong 🇭🇰 (free)+- Mumbai, India 🇮🇳+- Singapore, Singapore 🇸🇬+- Tokyo, Japan 🇯🇵++__Europe__++- Amsterdam, Netherlands 🇳🇱 (free)+- Bucharest, Romania 🇷🇴+- Frankfurt, Germany 🇩🇪+- London, United Kingdom 🇬🇧+- Madrid, Spain 🇪🇸+- Paris, France 🇫🇷+- Stockholm, Sweden 🇸🇪+- Warsaw, Poland 🇵🇱++__North America__++- Ashburn, Virginia, USA 🇺🇸 (free)+- Atlanta, Georgia, USA 🇺🇸+- Boston, Massachusetts, USA 🇺🇸+- Chicago, Illinois, USA 🇺🇸+- Dallas, Texas, USA 🇺🇸+- Denver, Colorado, USA 🇺🇸+- Guadalajara, Mexico 🇲🇽+- Los Angeles, California, USA 🇺🇸+- Miami, Florida, USA 🇺🇸+- Montreal, Canada 🇨🇦+- Phoenix, Arizona, USA 🇺🇸+- Queretaro, Mexico 🇲🇽+- Seattle, Washington, USA 🇺🇸+- San Jose, California, USA 🇺🇸+- Toronto, Canada 🇨🇦++__South America__++- Bogota, Colombia 🇨🇴+- Buenos Aires, Argentina 🇦🇷+- Rio de Janeiro, Brazil 🇧🇷+- Sao Paulo, Brazil 🇧🇷 (free)+- Santiago, Chile 🇨🇱++__Oceania__++- Sydney, Australia 🇦🇺 (free)++### Frequency++**Type:** String (required)+**Format:** Duration string (e.g., `30s`, `1m`, `1h`)++The interval at which the TCP monitor will attempt to connect to the target URI. Supported frequencies:+- `30 seconds`+- `1 minute`+- `5 minutes`+- `10 minutes`+- `30 minutes`+- `1 hour`++### Response Time Thresholds++#### Timeout++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for a successful TCP connection. If the connection cannot be established within this time, the check is considered a failure.++#### Degraded++**Type:** Duration (optional)++The duration after which a TCP connection attempt is considered to be in a degraded performance state. This allows for early warning of network latency or service slowdowns.++### Retry++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will automatically retry a failed TCP connection attempt before reporting a definitive error. For example: `3`++### OpenTelemetry++Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.++#### OTLP Endpoint++**Type:** String (optional)+**Protocol:** HTTP only++The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported. Only HTTP endpoints are supported for metric export.++#### OTLP Headers++**Type:** Key-value pairs (optional)++Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.++**Common example:**+```+Authorization: Bearer <your_token>+```++## Related resources++- **[Create Your First Monitor](/docs/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.+- **[CLI Reference](/docs/reference/cli-reference)** - Guide to managing openstatus monitors programmatically using the command-line interface.diff --git a/apps/web/src/content/pages/docs/reference/terraform.mdx b/apps/web/src/content/pages/docs/reference/terraform.mdxnew file mode 100644index 000000000..2ee349049--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/terraform.mdx@@ -0,0 +1,839 @@+---+category: Reference+title: Terraform Provider Reference+description: Technical specification for the openstatus Terraform Provider.+---++## Overview++The openstatus Terraform provider enables you to manage your monitoring infrastructure programmatically using HashiCorp Terraform. Define monitors, notification channels, and status pages as code — with full support for version control, automated deployments, and IaC workflows.++**Key capabilities:**+- Manage HTTP, TCP, and DNS monitors with assertions+- Configure notification channels (Slack, PagerDuty, email, webhooks, and more)+- Create and manage status pages with component groups+- Import existing resources into Terraform state++## Installation++Declare the provider in your Terraform configuration. Terraform will automatically download it when you run `terraform init`.++```terraform+terraform {+ required_providers {+ openstatus = {+ source = "openstatusHQ/openstatus"+ version = "~> 0.1"+ }+ }+}+```++For the latest version, refer to the [Terraform Registry](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest).++## Provider Configuration++```terraform+provider "openstatus" {+ api_token = "YOUR_OPENSTATUS_API_TOKEN" # or set OPENSTATUS_API_TOKEN env var+}+```++| Argument | Type | Required | Description |+| :---------- | :------- | :------- | :-------------------------------------------------------------------------- |+| `api_token` | `string` | Yes | Your openstatus API token. Can also be set via the `OPENSTATUS_API_TOKEN` environment variable. |+| `base_url` | `string` | No | Base URL for the openstatus API. Defaults to `https://api.openstatus.dev/rpc`. |++## Resources++### `openstatus_http_monitor`++Manages an HTTP monitor with support for custom headers, request bodies, and response assertions.++**Arguments:**++| Argument | Type | Required | Default | Description |+| :----------------- | :-------------- | :------- | :------- | :-------------------------------------------------------------------------- |+| `name` | `string` | Yes | | Monitor name (max 256 chars). |+| `url` | `string` | Yes | | URL to monitor (max 2048 chars). |+| `periodicity` | `string` | Yes | | Check frequency: `30s`, `1m`, `5m`, `10m`, `30m`, `1h`. |+| `method` | `string` | No | `"GET"` | HTTP method: `GET`, `POST`, `HEAD`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`. |+| `body` | `string` | No | `""` | Request body for `POST`, `PUT`, `PATCH` methods. |+| `timeout` | `number` | No | `45000` | Timeout in milliseconds (0–120000). |+| `degraded_at` | `number` | No | computed | Response time threshold (ms) after which the monitor is considered degraded. |+| `retry` | `number` | No | `3` | Number of retries on failure (0–10). |+| `follow_redirects` | `bool` | No | `true` | Whether to follow HTTP redirects. |+| `active` | `bool` | No | `false` | Whether the monitor is active. |+| `public` | `bool` | No | `false` | Whether the monitor is visible on your public status page. |+| `description` | `string` | No | | Monitor description (max 1024 chars). |+| `regions` | `set(string)` | No | | Regions to monitor from. See [Available Regions](#available-regions). |++**Blocks:**++- **`headers`** (max 20) — Custom HTTP headers to include with each request.+ - `key` (string, required) — Header name.+ - `value` (string, required) — Header value.++- **`status_code_assertions`** (max 10) — Assert on response status codes.+ - `target` (number, required) — Expected status code (100–599).+ - `comparator` (string, required) — One of: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`.++- **`body_assertions`** (max 10) — Assert on response body content.+ - `target` (string, required) — Expected value.+ - `comparator` (string, required) — One of: `contains`, `not_contains`, `eq`, `neq`, `empty`, `not_empty`, `gt`, `gte`, `lt`, `lte`.++- **`header_assertions`** (max 10) — Assert on response headers.+ - `key` (string, required) — Header name to assert on.+ - `target` (string, required) — Expected value.+ - `comparator` (string, required) — Same comparators as `body_assertions`.++**Read-only attributes:** `id` (string), `status` (string: `active`, `degraded`, `error`, `unknown`).++**Example — Basic health check:**++```terraform+resource "openstatus_http_monitor" "website" {+ name = "Website Availability"+ url = "https://www.example.com"+ periodicity = "1m"+ active = true+ public = true+ regions = ["fly-iad", "fly-ams", "fly-syd"]+}+```++**Example — API monitor with assertions and headers:**++```terraform+resource "openstatus_http_monitor" "api" {+ name = "API Health Check"+ description = "Monitors the /health endpoint with full assertions."+ url = "https://api.example.com/health"+ periodicity = "5m"+ method = "GET"+ timeout = 30000+ active = true+ regions = ["fly-iad", "fly-ams", "fly-nrt"]++ headers {+ key = "Authorization"+ value = "Bearer ${var.api_token}"+ }++ headers {+ key = "Accept"+ value = "application/json"+ }++ status_code_assertions {+ target = 200+ comparator = "eq"+ }++ body_assertions {+ target = "ok"+ comparator = "contains"+ }++ header_assertions {+ key = "Content-Type"+ target = "application/json"+ comparator = "contains"+ }+}+```++**Example — POST monitor with request body:**++```terraform+resource "openstatus_http_monitor" "webhook" {+ name = "Webhook Endpoint"+ url = "https://api.example.com/webhooks/health"+ periodicity = "10m"+ method = "POST"+ active = true+ regions = ["fly-iad"]++ headers {+ key = "Content-Type"+ value = "application/json"+ }++ body = jsonencode({+ type = "health_check"+ })++ status_code_assertions {+ target = 202+ comparator = "eq"+ }+}+```++**Import:**++```bash+terraform import openstatus_http_monitor.website <monitor_id>+```++---++### `openstatus_tcp_monitor`++Manages a TCP connection monitor to verify that a port is open and reachable.++**Arguments:**++| Argument | Type | Required | Default | Description |+| :------------ | :------------ | :------- | :------- | :----------------------------------------------------------------- |+| `name` | `string` | Yes | | Monitor name (max 256 chars). |+| `uri` | `string` | Yes | | Target in `host:port` format (max 2048 chars). |+| `periodicity` | `string` | Yes | | Check frequency: `30s`, `1m`, `5m`, `10m`, `30m`, `1h`. |+| `timeout` | `number` | No | `45000` | Timeout in milliseconds (0–120000). |+| `degraded_at` | `number` | No | computed | Degradation threshold in milliseconds. |+| `retry` | `number` | No | `3` | Number of retries on failure (0–10). |+| `active` | `bool` | No | `false` | Whether the monitor is active. |+| `public` | `bool` | No | `false` | Whether the monitor is publicly visible. |+| `description` | `string` | No | | Monitor description (max 1024 chars). |+| `regions` | `set(string)` | No | | Regions to monitor from. See [Available Regions](#available-regions). |++**Read-only attributes:** `id` (string), `status` (string).++**Example — Database port check:**++```terraform+resource "openstatus_tcp_monitor" "database" {+ name = "PostgreSQL Port Check"+ description = "Ensures the database port is open and reachable."+ uri = "db.example.com:5432"+ periodicity = "1m"+ timeout = 10000+ active = true+ regions = ["fly-iad", "fly-fra"]+}+```++**Example — Redis monitor:**++```terraform+resource "openstatus_tcp_monitor" "redis" {+ name = "Redis Connection"+ uri = "redis.example.com:6379"+ periodicity = "30s"+ active = true+ regions = ["fly-iad", "fly-ams", "fly-nrt"]+}+```++**Import:**++```bash+terraform import openstatus_tcp_monitor.database <monitor_id>+```++---++### `openstatus_dns_monitor`++Manages a DNS monitor with support for record type assertions.++**Arguments:**++| Argument | Type | Required | Default | Description |+| :------------ | :------------ | :------- | :------- | :----------------------------------------------------------------- |+| `name` | `string` | Yes | | Monitor name (max 256 chars). |+| `uri` | `string` | Yes | | Domain name to monitor (max 2048 chars). |+| `periodicity` | `string` | Yes | | Check frequency: `30s`, `1m`, `5m`, `10m`, `30m`, `1h`. |+| `timeout` | `number` | No | `45000` | Timeout in milliseconds (0–120000). |+| `degraded_at` | `number` | No | computed | Degradation threshold in milliseconds. |+| `retry` | `number` | No | `3` | Number of retries on failure (0–10). |+| `active` | `bool` | No | `false` | Whether the monitor is active. |+| `public` | `bool` | No | `false` | Whether the monitor is publicly visible. |+| `description` | `string` | No | | Monitor description (max 1024 chars). |+| `regions` | `set(string)` | No | | Regions to monitor from. See [Available Regions](#available-regions). |++**Blocks:**++- **`record_assertions`** (max 10) — Assert on DNS record values.+ - `record` (string, required) — DNS record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`.+ - `target` (string, required) — Expected value.+ - `comparator` (string, required) — One of: `eq`, `neq`, `contains`, `not_contains`.++**Read-only attributes:** `id` (string), `status` (string).++**Example — A record validation:**++```terraform+resource "openstatus_dns_monitor" "main_domain" {+ name = "DNS A Record Check"+ description = "Verifies that example.com resolves to the correct IP."+ uri = "example.com"+ periodicity = "10m"+ active = true+ regions = ["fly-iad", "fly-ams"]++ record_assertions {+ record = "A"+ comparator = "eq"+ target = "93.184.216.34"+ }+}+```++**Example — MX record validation:**++```terraform+resource "openstatus_dns_monitor" "email" {+ name = "Email MX Record Check"+ uri = "example.com"+ periodicity = "30m"+ active = true+ regions = ["fly-iad"]++ record_assertions {+ record = "MX"+ comparator = "contains"+ target = "mail.example.com"+ }+}+```++**Import:**++```bash+terraform import openstatus_dns_monitor.main_domain <monitor_id>+```++---++### `openstatus_notification`++Manages a notification channel. Supports 12 provider types: Discord, Email, Slack, PagerDuty, OpsGenie, Webhook, Telegram, SMS, WhatsApp, Google Chat, Grafana OnCall, and ntfy.++**Arguments:**++| Argument | Type | Required | Description |+| :-------------- | :------------ | :------- | :------------------------------------------------------ |+| `name` | `string` | No | Notification channel name. |+| `provider_type` | `string` | Yes | Provider type (see supported values below). |+| `monitor_ids` | `set(string)` | No | Set of monitor IDs to associate with this notification. |++**Supported `provider_type` values:** `discord`, `email`, `slack`, `pagerduty`, `opsgenie`, `webhook`, `telegram`, `sms`, `whatsapp`, `google_chat`, `grafana_oncall`, `ntfy`.++**Provider-specific blocks** — use exactly one block matching your `provider_type`:++| Block | Arguments |+| :-------------- | :----------------------------------------------------------------------------------------------------- |+| `discord` | `webhook_url` (string, required, sensitive) |+| `email` | `email` (string, required) |+| `slack` | `webhook_url` (string, required, sensitive) |+| `pagerduty` | `integration_key` (string, required, sensitive) |+| `opsgenie` | `api_key` (string, required, sensitive), `region` (string, required: `us` or `eu`) |+| `webhook` | `endpoint` (string, required), `headers` (optional list of `key`/`value` objects) |+| `telegram` | `chat_id` (string, required) |+| `sms` | `phone_number` (string, required) |+| `whatsapp` | `phone_number` (string, required) |+| `google_chat` | `webhook_url` (string, required, sensitive) |+| `grafana_oncall` | `webhook_url` (string, required, sensitive) |+| `ntfy` | `topic` (string, required), `server_url` (string, optional), `token` (string, optional, sensitive) |++**Read-only attributes:** `id` (string), `created_at` (string), `updated_at` (string).++**Example — Slack notification:**++```terraform+resource "openstatus_notification" "slack_alerts" {+ name = "Slack Alerts"+ provider_type = "slack"+ monitor_ids = [openstatus_http_monitor.api.id]++ slack {+ webhook_url = var.slack_webhook_url+ }+}+```++**Example — PagerDuty notification:**++```terraform+resource "openstatus_notification" "pagerduty" {+ name = "PagerDuty Escalation"+ provider_type = "pagerduty"+ monitor_ids = [+ openstatus_http_monitor.api.id,+ openstatus_tcp_monitor.database.id,+ ]++ pagerduty {+ integration_key = var.pagerduty_key+ }+}+```++**Example — Email notification:**++```terraform+resource "openstatus_notification" "email" {+ name = "On-Call Email"+ provider_type = "email"+ monitor_ids = [openstatus_http_monitor.api.id]++ email {+ email = "[email protected]"+ }+}+```++**Example — Custom webhook:**++```terraform+resource "openstatus_notification" "custom_webhook" {+ name = "Custom Webhook"+ provider_type = "webhook"++ webhook {+ endpoint = "https://api.example.com/alerts"++ headers {+ key = "Authorization"+ value = "Bearer ${var.webhook_token}"+ }++ headers {+ key = "Content-Type"+ value = "application/json"+ }+ }+}+```++**Example — Discord notification:**++```terraform+resource "openstatus_notification" "discord" {+ name = "Discord Alerts"+ provider_type = "discord"++ discord {+ webhook_url = var.discord_webhook_url+ }+}+```++**Import:**++```bash+terraform import openstatus_notification.slack_alerts <notification_id>+```++---++### `openstatus_status_page`++Manages a status page with access control and branding.++**Arguments:**++| Argument | Type | Required | Description |+| :------------------- | :------------- | :------- | :----------------------------------------------------------------------------- |+| `title` | `string` | Yes | Page title (1–256 chars). |+| `slug` | `string` | Yes | URL slug (1–256 chars). Used in the status page URL. |+| `description` | `string` | No | Page description (max 1024 chars). |+| `homepage_url` | `string` | No | Link to your homepage. |+| `contact_url` | `string` | No | Link to your contact page. |+| `icon` | `string` | No | URL of the icon to display. |+| `custom_domain` | `string` | No | Custom domain (DNS must point to openstatus first). |+| `access_type` | `string` | No | Access control: `public`, `password`, or `email-domain`. |+| `password` | `string` | No | Required when `access_type` is `password`. Sensitive. |+| `auth_email_domains` | `list(string)` | No | Required when `access_type` is `email-domain`. |++**Read-only attributes:** `id` (string), `published` (bool), `theme` (string: `system`, `light`, `dark`), `created_at` (string), `updated_at` (string).++**Example — Public status page:**++```terraform+resource "openstatus_status_page" "main" {+ title = "Example Inc. Status"+ slug = "example-status"+ description = "Real-time status for all Example Inc. services."+ homepage_url = "https://example.com"+ contact_url = "https://example.com/support"+}+```++**Example — Password-protected status page:**++```terraform+resource "openstatus_status_page" "internal" {+ title = "Internal Status"+ slug = "internal-status"+ description = "Status page for internal services."+ access_type = "password"+ password = var.status_page_password+}+```++**Example — Email-domain restricted status page:**++```terraform+resource "openstatus_status_page" "company" {+ title = "Company Status"+ slug = "company-status"+ access_type = "email-domain"+ auth_email_domains = ["example.com", "subsidiary.com"]+}+```++**Import:**++```bash+terraform import openstatus_status_page.main <page_id>+```++---++### `openstatus_status_page_component`++Manages a component on a status page. Components can be linked to a monitor or be static.++**Arguments:**++| Argument | Type | Required | Description |+| :------------ | :------- | :------- | :--------------------------------------------------------------------------- |+| `page_id` | `string` | Yes | Status page ID this component belongs to. Forces replacement if changed. |+| `type` | `string` | Yes | Component type: `monitor` or `static`. Forces replacement if changed. |+| `monitor_id` | `string` | No | Required when `type` is `monitor`. The monitor ID to display. |+| `name` | `string` | No | Component display name (max 256 chars). |+| `description` | `string` | No | Component description (max 1024 chars). |+| `order` | `number` | No | Display order on the status page. |+| `group_id` | `string` | No | Component group ID this belongs to. |+| `group_order` | `number` | No | Display order within its group. |++**Read-only attributes:** `id` (string), `created_at` (string), `updated_at` (string).++**Example — Monitor component:**++```terraform+resource "openstatus_status_page_component" "api" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_http_monitor.api.id+ name = "API"+ order = 1+}+```++**Example — Static component:**++```terraform+resource "openstatus_status_page_component" "third_party" {+ page_id = openstatus_status_page.main.id+ type = "static"+ name = "Third-party Services"+ description = "Status of external dependencies."+ order = 2+}+```++**Import:**++```bash+terraform import openstatus_status_page_component.api <page_id>/<component_id>+```++---++### `openstatus_status_page_component_group`++Manages a component group on a status page, allowing you to organize components visually.++**Arguments:**++| Argument | Type | Required | Description |+| :-------- | :------- | :------- | :----------------------------------------------------------------------- |+| `page_id` | `string` | Yes | Status page ID this group belongs to. Forces replacement if changed. |+| `name` | `string` | Yes | Group name (1–256 chars). |++**Read-only attributes:** `id` (string), `created_at` (string), `updated_at` (string).++**Example:**++```terraform+resource "openstatus_status_page_component_group" "infrastructure" {+ page_id = openstatus_status_page.main.id+ name = "Infrastructure"+}++resource "openstatus_status_page_component_group" "applications" {+ page_id = openstatus_status_page.main.id+ name = "Applications"+}+```++**Import:**++```bash+terraform import openstatus_status_page_component_group.infrastructure <page_id>/<group_id>+```++## Data Sources++### `openstatus_monitor`++Look up a single monitor by ID. Works for HTTP, TCP, and DNS monitors.++```terraform+data "openstatus_monitor" "existing" {+ id = "123"+}++output "monitor_name" {+ value = data.openstatus_monitor.existing.name+}++output "monitor_type" {+ value = data.openstatus_monitor.existing.type+}+```++**Computed attributes:** `type` (`http`, `tcp`, `dns`), `name`, `url` (HTTP only), `uri` (TCP/DNS only), `periodicity`, `method` (HTTP only), `active`, `public`, `description`, `timeout`, `status`.++---++### `openstatus_monitors`++List all monitors with pagination.++```terraform+data "openstatus_monitors" "all" {+ limit = 100+ offset = 0+}++output "total_monitors" {+ value = length(data.openstatus_monitors.all.monitors)+}+```++| Argument | Type | Required | Default | Description |+| :------- | :------- | :------- | :------ | :----------------------- |+| `limit` | `number` | No | `50` | Max results (1–100). |+| `offset` | `number` | No | `0` | Pagination offset. |++**Computed:** `monitors` — list of objects with `id`, `name`, `type`.++---++### `openstatus_notification`++Look up a notification channel by ID.++```terraform+data "openstatus_notification" "existing" {+ id = "456"+}++output "notification_provider" {+ value = data.openstatus_notification.existing.provider_type+}+```++**Computed attributes:** `name`, `provider_type`, `monitor_ids`, `created_at`, `updated_at`.++---++### `openstatus_status_page`++Look up a status page by ID.++```terraform+data "openstatus_status_page" "existing" {+ id = "789"+}++output "status_page_url" {+ value = data.openstatus_status_page.existing.slug+}+```++**Computed attributes:** `title`, `slug`, `description`, `homepage_url`, `contact_url`, `icon`, `custom_domain`, `published`, `access_type`, `password` (sensitive), `auth_email_domains`, `theme`, `created_at`, `updated_at`.++## Available Regions++Monitors can run from any of the following 28 regions:++**Fly.io:**+`fly-ams`, `fly-arn`, `fly-bom`, `fly-cdg`, `fly-dfw`, `fly-ewr`, `fly-fra`, `fly-gru`, `fly-iad`, `fly-jnb`, `fly-lax`, `fly-lhr`, `fly-nrt`, `fly-ord`, `fly-sjc`, `fly-sin`, `fly-syd`, `fly-yyz`++**Koyeb:**+`koyeb-fra`, `koyeb-par`, `koyeb-sfo`, `koyeb-sin`, `koyeb-tyo`, `koyeb-was`++**Railway:**+`railway-us-west2`, `railway-us-east4`, `railway-europe-west4`, `railway-asia-southeast1`++## Full End-to-End Example++This example sets up a complete monitoring stack: HTTP and TCP monitors, Slack notifications, and a public status page with grouped components.++```terraform+terraform {+ required_providers {+ openstatus = {+ source = "openstatusHQ/openstatus"+ version = "~> 0.1"+ }+ }+}++provider "openstatus" {+ api_token = var.openstatus_api_token+}++# --- Variables ---++variable "openstatus_api_token" {+ type = string+ sensitive = true+}++variable "slack_webhook_url" {+ type = string+ sensitive = true+}++# --- Monitors ---++resource "openstatus_http_monitor" "api" {+ name = "API Health"+ description = "Monitors the main API health endpoint."+ url = "https://api.example.com/health"+ periodicity = "5m"+ method = "GET"+ timeout = 30000+ active = true+ public = true+ regions = ["fly-iad", "fly-ams", "fly-nrt"]++ status_code_assertions {+ target = 200+ comparator = "eq"+ }++ body_assertions {+ target = "ok"+ comparator = "contains"+ }+}++resource "openstatus_http_monitor" "website" {+ name = "Website"+ url = "https://www.example.com"+ periodicity = "1m"+ active = true+ public = true+ regions = ["fly-iad", "fly-ams", "fly-syd"]++ status_code_assertions {+ target = 200+ comparator = "eq"+ }+}++resource "openstatus_tcp_monitor" "database" {+ name = "PostgreSQL"+ uri = "db.example.com:5432"+ periodicity = "1m"+ timeout = 10000+ active = true+ regions = ["fly-iad"]+}++resource "openstatus_dns_monitor" "domain" {+ name = "DNS Resolution"+ uri = "example.com"+ periodicity = "10m"+ active = true+ regions = ["fly-iad", "fly-ams"]++ record_assertions {+ record = "A"+ comparator = "eq"+ target = "93.184.216.34"+ }+}++# --- Notifications ---++resource "openstatus_notification" "slack" {+ name = "Slack Alerts"+ provider_type = "slack"+ monitor_ids = [+ openstatus_http_monitor.api.id,+ openstatus_http_monitor.website.id,+ openstatus_tcp_monitor.database.id,+ ]++ slack {+ webhook_url = var.slack_webhook_url+ }+}++# --- Status Page ---++resource "openstatus_status_page" "main" {+ title = "Example Inc. Status"+ slug = "example-status"+ description = "Real-time status for all Example Inc. services."+ homepage_url = "https://example.com"+ contact_url = "https://example.com/support"+}++resource "openstatus_status_page_component_group" "web" {+ page_id = openstatus_status_page.main.id+ name = "Web Services"+}++resource "openstatus_status_page_component_group" "infra" {+ page_id = openstatus_status_page.main.id+ name = "Infrastructure"+}++resource "openstatus_status_page_component" "api_component" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_http_monitor.api.id+ name = "API"+ group_id = openstatus_status_page_component_group.web.id+ order = 1+ group_order = 1+}++resource "openstatus_status_page_component" "website_component" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_http_monitor.website.id+ name = "Website"+ group_id = openstatus_status_page_component_group.web.id+ order = 1+ group_order = 2+}++resource "openstatus_status_page_component" "db_component" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_tcp_monitor.database.id+ name = "Database"+ group_id = openstatus_status_page_component_group.infra.id+ order = 2+ group_order = 1+}+```++## Related Resources++- **[HTTP Monitor Reference](/docs/reference/http-monitor)** — Detailed specification for HTTP monitor configuration.+- **[TCP Monitor Reference](/docs/reference/tcp-monitor)** — Detailed specification for TCP monitor configuration.+- **[DNS Monitor Reference](/docs/reference/dns-monitor)** — Detailed specification for DNS monitor configuration.+- **[CLI Reference](/docs/reference/cli-reference)** — Manage monitors using the openstatus command-line interface.+- **[Terraform Registry](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest)** — Official provider page with version history.+- **[Provider Source Code](https://github.com/openstatusHQ/terraform-provider-openstatus)** — GitHub repository for the Terraform provider.diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/authentication.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/authentication.mdxnew file mode 100644index 000000000..b0e4bf2e5--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/authentication.mdx@@ -0,0 +1,84 @@+---+category: SDK+title: Authentication+description: "Configure API key authentication for the openstatus Node.js SDK"+---++## Recommended: createOpenStatusClient++Create a client with your API key. The key is automatically included in all requests via an interceptor.++```typescript+import { createOpenStatusClient } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++// No headers needed on individual calls+const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});+```++## Alternative: Manual Headers++Use the default `openstatus` client and pass headers on each call.++```typescript+import { openstatus } from "@openstatus/sdk-node";++const headers = {+ "x-openstatus-key": process.env.OPENSTATUS_API_KEY,+};++await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });+```++## Environment Variables++| Variable | Description | Default |+|----------|-------------|---------|+| `OPENSTATUS_API_KEY` | Your openstatus API key | Required for authenticated calls |+| `OPENSTATUS_API_URL` | Custom API endpoint | `https://api.openstatus.dev/rpc` |++Get your API key from the [openstatus dashboard](https://www.openstatus.dev/app).++## Scopes++Each API key carries a scope that controls what it can do:++- **Read-only** (`['read']`) — list/get endpoints only. Mutations return `403 Forbidden`. Recommended for AI agents and read-only dashboards.+- **Read & write** (`['write']`) — full workspace access. Required for CI/CD and automation.++Scope is set when the key is created and is **immutable** — to change it, revoke the key and issue a new one. Existing keys created before this feature shipped continue to work as Read & write.++`GET /v1/whoami` echoes the resolved actor's scopes back so a client can introspect what it's allowed to do without probe-and-fail:++```json+{+ "name": "Acme",+ "slug": "acme",+ "plan": "team",+ "actor": {+ "type": "apiKey",+ "keyId": "42",+ "scopes": ["read"]+ }+}+```++A read-only key can revoke itself via `DELETE /v1/api-key/{id}` (the only carve-out — without it, a leaked read-only key would have no rotation path other than the dashboard). Revoking a *different* key from a read-only actor returns `403 Forbidden`.++## Custom Base URL++For self-hosted instances or staging environments:++```typescript+import { createOpenStatusClient } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+ baseUrl: "https://api.staging.example.com/rpc",+});+```++The `baseUrl` option takes precedence over the `OPENSTATUS_API_URL` environment variable.diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/error-handling.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/error-handling.mdxnew file mode 100644index 000000000..aa5ad5630--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/error-handling.mdx@@ -0,0 +1,62 @@+---+category: SDK+title: Error Handling+description: "Handle errors and implement retry strategies with the openstatus Node.js SDK"+---++The SDK uses ConnectRPC. Errors are thrown as `ConnectError` instances from the `@connectrpc/connect` package.++```typescript+import { ConnectError } from "@connectrpc/connect";++try {+ await client.monitor.v1.MonitorService.deleteMonitor({ id: "invalid" });+} catch (error) {+ if (error instanceof ConnectError) {+ console.error(`Code: ${error.code}`);+ console.error(`Message: ${error.message}`);+ }+}+```++## Common Error Codes++| Code | Description |+|------|-------------|+| `unauthenticated` | Missing or invalid API key |+| `not_found` | Resource does not exist |+| `invalid_argument` | Validation failure (e.g., missing required field, value out of range) |+| `permission_denied` | No access to this workspace or resource |+| `already_exists` | Duplicate resource (e.g., slug already taken) |++## Retry Strategy++ConnectRPC does not retry by default. For transient failures (`unavailable`, `deadline_exceeded`), implement your own retry logic:++```typescript+import { Code, ConnectError } from "@connectrpc/connect";++async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {+ for (let attempt = 0; attempt <= maxRetries; attempt++) {+ try {+ return await fn();+ } catch (error) {+ if (+ error instanceof ConnectError &&+ (error.code === Code.Unavailable ||+ error.code === Code.DeadlineExceeded) &&+ attempt < maxRetries+ ) {+ await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));+ continue;+ }+ throw error;+ }+ }+ throw new Error("Unreachable");+}++const { httpMonitors } = await withRetry(() =>+ client.monitor.v1.MonitorService.listMonitors({})+);+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/getting-started.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/getting-started.mdxnew file mode 100644index 000000000..c3735f5bd--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/getting-started.mdx@@ -0,0 +1,153 @@+---+category: SDK+title: Getting Started+description: "Install and start using the openstatus Node.js SDK"+---+++## Get Your API Key++Before using the SDK, you need an API key:++1. Log in to the [openstatus dashboard](https://www.openstatus.dev/app/login)+2. Go to **Settings** > **API Keys**+3. Click **Create API Key** and copy it++<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>++## Installation++### npm++```bash+npm install @openstatus/sdk-node+```++### JSR++```bash+npx jsr add @openstatus/sdk-node+```++### Deno++```typescript+import { createOpenStatusClient } from "jsr:@openstatus/sdk-node";+```++### Bun++```bash+bun add @openstatus/sdk-node+```++## Quick Start++```typescript+import {+ createOpenStatusClient,+ Periodicity,+ Region,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++// Create an HTTP monitor+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({+ monitor: {+ name: "My API",+ url: "https://api.example.com/health",+ periodicity: Periodicity.PERIODICITY_1M,+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],+ active: true,+ },+});++console.log(`Monitor created: ${monitor?.id}`);++// List all monitors+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =+ await client.monitor.v1.MonitorService.listMonitors({});++console.log(`Found ${totalSize} monitors`);+```++## Runtime Support++| Runtime | Version | Module Format |+|---------|---------|---------------|+| Node.js | 18+ | ESM and CJS |+| Deno | 2+ | ESM (native) |+| Bun | Latest | ESM |++## Full Workflow Example++A complete example: create a monitor, set up a status page, add the monitor as a component, configure a Slack notification, and check overall status.++```typescript+import {+ createOpenStatusClient,+ NotificationProvider,+ Periodicity,+ Region,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++// 1. Check API health+const health = await client.health.v1.HealthService.check({});+console.log(`API status: ${health.status}`);++// 2. Create an HTTP monitor+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({+ monitor: {+ name: "Production API",+ url: "https://api.example.com/health",+ periodicity: Periodicity.PERIODICITY_1M,+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],+ active: true,+ },+});++// 3. Create a status page+const { statusPage } = await client.statusPage.v1.StatusPageService+ .createStatusPage({+ title: "Example Status",+ slug: "example-status",+ description: "Status page for Example services",+ });++// 4. Add the monitor as a component+const { component } = await client.statusPage.v1.StatusPageService+ .addMonitorComponent({+ pageId: statusPage!.id,+ monitorId: monitor!.id,+ name: "Production API",+ });++// 5. Set up Slack notifications+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Slack Alerts",+ provider: NotificationProvider.SLACK,+ data: {+ data: {+ case: "slack",+ value: { webhookUrl: "https://hooks.slack.com/services/..." },+ },+ },+ monitorIds: [monitor!.id],+ });++// 6. Check overall status+const { overallStatus } = await client.statusPage.v1.StatusPageService+ .getOverallStatus({+ identifier: { case: "id", value: statusPage!.id },+ });++console.log(`Overall status: ${overallStatus}`);+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/health-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/health-service.mdxnew file mode 100644index 000000000..f86b7eb1b--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/health-service.mdx@@ -0,0 +1,24 @@+---+category: SDK+title: Health Service+description: "Check the openstatus API health status using the Node.js SDK"+---++Check API health status. No authentication required.++```typescript+import { openstatus, ServingStatus } from "@openstatus/sdk-node";++const { status } = await openstatus.health.v1.HealthService.check({});+console.log(ServingStatus[status]); // "SERVING"+```++Or with a configured client:++```typescript+import { createOpenStatusClient, ServingStatus } from "@openstatus/sdk-node";++const client = createOpenStatusClient();+const { status } = await client.health.v1.HealthService.check({});+console.log(ServingStatus[status]); // "SERVING"+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/maintenance-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/maintenance-service.mdxnew file mode 100644index 000000000..84038b6cf--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/maintenance-service.mdx@@ -0,0 +1,72 @@+---+category: SDK+title: Maintenance Service+description: "Manage scheduled maintenance windows with the openstatus Node.js SDK"+---++Manage scheduled maintenance windows. The Maintenance Service provides 5 RPC methods.++## Create Maintenance Window++```typescript+const { maintenance } = await client.maintenance.v1.MaintenanceService+ .createMaintenance({+ title: "Database Upgrade",+ message: "We will be upgrading our database infrastructure.",+ from: "2024-01-20T02:00:00Z",+ to: "2024-01-20T04:00:00Z",+ pageId: "page_123",+ pageComponentIds: ["comp_456"],+ notify: true,+ });++console.log(`Maintenance created: ${maintenance?.id}`);+```++All date fields (`from`, `to`) must be in RFC 3339 format.++## List Maintenances++List maintenance windows with optional page filtering.++```typescript+const { maintenances, totalSize } = await client.maintenance.v1+ .MaintenanceService.listMaintenances({+ limit: 10,+ offset: 0,+ pageId: "page_123",+ });++console.log(`Found ${totalSize} maintenance windows`);+```++## Get / Update / Delete Maintenance Windows++### Get Maintenance++```typescript+const { maintenance } = await client.maintenance.v1.MaintenanceService+ .getMaintenance({ id: "maint_123" });++console.log(`Title: ${maintenance?.title}`);+console.log(`From: ${maintenance?.from}`);+console.log(`To: ${maintenance?.to}`);+```++### Update Maintenance++```typescript+const { maintenance } = await client.maintenance.v1.MaintenanceService+ .updateMaintenance({+ id: "maint_123",+ title: "Extended Database Upgrade",+ to: "2024-01-20T06:00:00Z",+ });+```++### Delete Maintenance++```typescript+const { success } = await client.maintenance.v1.MaintenanceService+ .deleteMaintenance({ id: "maint_123" });+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/monitor-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/monitor-service.mdxnew file mode 100644index 000000000..fc9277310--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/monitor-service.mdx@@ -0,0 +1,348 @@+---+category: SDK+title: Monitor Service+description: "Create and manage HTTP, TCP, and DNS monitors with the openstatus Node.js SDK"+---++Manage HTTP, TCP, and DNS monitors. The Monitor Service provides 12 RPC methods for creating, updating, listing, triggering, deleting, and querying monitor status and metrics.++All examples assume you have created a client:++```typescript+import { createOpenStatusClient } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});+```++## HTTP Monitors++### Create HTTP Monitor++```typescript+import {+ createOpenStatusClient,+ HTTPMethod,+ NumberComparator,+ Periodicity,+ Region,+ StringComparator,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({+ monitor: {+ name: "My API",+ url: "https://api.example.com/health",+ periodicity: Periodicity.PERIODICITY_1M,+ method: HTTPMethod.HTTP_METHOD_GET,+ regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],+ active: true,+ timeout: BigInt(30000),+ retry: BigInt(3),+ followRedirects: true,+ degradedAt: BigInt(5000),+ headers: [+ { key: "Authorization", value: "Bearer my-token" },+ ],+ statusCodeAssertions: [+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },+ ],+ bodyAssertions: [+ { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },+ ],+ headerAssertions: [+ {+ key: "content-type",+ comparator: StringComparator.CONTAINS,+ target: "application/json",+ },+ ],+ description: "Health check for the production API",+ public: false,+ openTelemetry: {+ endpoint: "https://otel.example.com/v1/traces",+ headers: [{ key: "Authorization", value: "Bearer otel-token" }],+ },+ },+});++console.log(`Created monitor: ${monitor?.id}`);+```++### Update HTTP Monitor++Updates are partial — only include the fields you want to change.++```typescript+const { monitor } = await client.monitor.v1.MonitorService.updateHTTPMonitor({+ id: "mon_123",+ monitor: {+ name: "Updated API Monitor",+ active: false,+ },+});+```++### HTTP Monitor Options++| Option | Type | Required | Description |+|--------|------|----------|-------------|+| `name` | string | Yes | Monitor name (max 256 chars) |+| `url` | string | Yes | URL to monitor (max 2048 chars) |+| `periodicity` | Periodicity | Yes | Check interval |+| `method` | HTTPMethod | No | HTTP method (default: GET) |+| `body` | string | No | Request body |+| `headers` | Headers[] | No | Custom headers `{ key, value }[]` |+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |+| `followRedirects` | boolean | No | Follow redirects (default: true) |+| `regions` | Region[] | No | Regions for checks |+| `active` | boolean | No | Enable monitoring (default: false) |+| `public` | boolean | No | Public visibility (default: false) |+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |+| `description` | string | No | Monitor description (max 1024 chars) |+| `statusCodeAssertions` | StatusCodeAssertion[] | No | Status code assertions |+| `bodyAssertions` | BodyAssertion[] | No | Body assertions |+| `headerAssertions` | HeaderAssertion[] | No | Header assertions |+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |++## TCP Monitors++### Create TCP Monitor++```typescript+import {+ createOpenStatusClient,+ Periodicity,+ Region,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { monitor } = await client.monitor.v1.MonitorService.createTCPMonitor({+ monitor: {+ name: "Database",+ uri: "db.example.com:5432",+ periodicity: Periodicity.PERIODICITY_5M,+ regions: [Region.FLY_AMS, Region.FLY_IAD],+ active: true,+ },+});+```++### Update TCP Monitor++```typescript+const { monitor } = await client.monitor.v1.MonitorService.updateTCPMonitor({+ id: "mon_123",+ monitor: {+ name: "Updated Database Monitor",+ },+});+```++### TCP Monitor Options++| Option | Type | Required | Description |+|--------|------|----------|-------------|+| `name` | string | Yes | Monitor name (max 256 chars) |+| `uri` | string | Yes | `host:port` to monitor (max 2048 chars) |+| `periodicity` | Periodicity | Yes | Check interval |+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |+| `regions` | Region[] | No | Regions for checks |+| `active` | boolean | No | Enable monitoring (default: false) |+| `public` | boolean | No | Public visibility (default: false) |+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |+| `description` | string | No | Monitor description (max 1024 chars) |+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |++## DNS Monitors++### Create DNS Monitor++```typescript+import {+ createOpenStatusClient,+ Periodicity,+ RecordComparator,+ Region,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { monitor } = await client.monitor.v1.MonitorService.createDNSMonitor({+ monitor: {+ name: "DNS Check",+ uri: "example.com",+ periodicity: Periodicity.PERIODICITY_10M,+ regions: [Region.FLY_AMS],+ active: true,+ recordAssertions: [+ {+ record: "A",+ comparator: RecordComparator.EQUAL,+ target: "93.184.216.34",+ },+ {+ record: "CNAME",+ comparator: RecordComparator.CONTAINS,+ target: "cdn",+ },+ ],+ },+});+```++### Update DNS Monitor++```typescript+const { monitor } = await client.monitor.v1.MonitorService.updateDNSMonitor({+ id: "mon_123",+ monitor: {+ name: "Updated DNS Check",+ },+});+```++### DNS Monitor Options++| Option | Type | Required | Description |+|--------|------|----------|-------------|+| `name` | string | Yes | Monitor name (max 256 chars) |+| `uri` | string | Yes | Domain to resolve (max 2048 chars) |+| `periodicity` | Periodicity | Yes | Check interval |+| `timeout` | bigint | No | Timeout in ms (default: 45000, max: 120000) |+| `retry` | bigint | No | Retry attempts (default: 3, max: 10) |+| `regions` | Region[] | No | Regions for checks |+| `active` | boolean | No | Enable monitoring (default: false) |+| `public` | boolean | No | Public visibility (default: false) |+| `degradedAt` | bigint | No | Latency threshold (ms) for degraded status |+| `description` | string | No | Monitor description (max 1024 chars) |+| `recordAssertions` | RecordAssertion[] | No | DNS record assertions |+| `openTelemetry` | OpenTelemetryConfig | No | OpenTelemetry export configuration |++## List Monitors++List all monitors with offset-based pagination. Returns monitors grouped by type.++```typescript+const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } =+ await client.monitor.v1.MonitorService.listMonitors({+ limit: 10,+ offset: 0,+ });++console.log(`Total: ${totalSize}`);+console.log(`HTTP: ${httpMonitors.length}`);+console.log(`TCP: ${tcpMonitors.length}`);+console.log(`DNS: ${dnsMonitors.length}`);+```++Pagination parameters:++| Parameter | Type | Description |+|-----------|------|-------------|+| `limit` | number (optional) | Max results to return (1–100, default 50) |+| `offset` | number (optional) | Number of results to skip (default 0) |++## Get Monitor++Get a single monitor by ID. The response uses a `MonitorConfig` oneof type that contains one of HTTP, TCP, or DNS configuration.++```typescript+const { monitor } = await client.monitor.v1.MonitorService.getMonitor({+ id: "mon_123",+});++if (monitor?.config.case === "http") {+ console.log(`HTTP Monitor: ${monitor.config.value.name} — ${monitor.config.value.url}`);+} else if (monitor?.config.case === "tcp") {+ console.log(`TCP Monitor: ${monitor.config.value.name} — ${monitor.config.value.uri}`);+} else if (monitor?.config.case === "dns") {+ console.log(`DNS Monitor: ${monitor.config.value.name} — ${monitor.config.value.uri}`);+}+```++## Trigger Monitor++Trigger an immediate check for a monitor.++```typescript+const { success } = await client.monitor.v1.MonitorService.triggerMonitor({+ id: "mon_123",+});++console.log(`Trigger successful: ${success}`);+```++## Delete Monitor++```typescript+const { success } = await client.monitor.v1.MonitorService.deleteMonitor({+ id: "mon_123",+});+```++## Get Monitor Status++Get the current status of a monitor across all configured regions.++```typescript+import {+ createOpenStatusClient,+ MonitorStatus,+ Region,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { id, regions } = await client.monitor.v1.MonitorService.getMonitorStatus(+ { id: "mon_123" },+);++for (const { region, status } of regions) {+ console.log(`${Region[region]}: ${MonitorStatus[status]}`);+}+```++## Get Monitor Summary++Get aggregated metrics and latency percentiles for a monitor over a time range.++```typescript+import { createOpenStatusClient, TimeRange } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const summary = await client.monitor.v1.MonitorService.getMonitorSummary({+ id: "mon_123",+ timeRange: TimeRange.TIME_RANGE_7D,+ regions: [],+});++console.log(`Last ping: ${summary.lastPingAt}`);+console.log(`Successful: ${summary.totalSuccessful}`);+console.log(`Degraded: ${summary.totalDegraded}`);+console.log(`Failed: ${summary.totalFailed}`);+console.log(`P50: ${summary.p50}ms`);+console.log(`P75: ${summary.p75}ms`);+console.log(`P90: ${summary.p90}ms`);+console.log(`P95: ${summary.p95}ms`);+console.log(`P99: ${summary.p99}ms`);+```++The latency fields (`p50`, `p75`, `p90`, `p95`, `p99`) and count fields (`totalSuccessful`, `totalDegraded`, `totalFailed`) are `bigint` values. The `regions` parameter is optional — pass an empty array to get metrics across all regions.diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/notification-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/notification-service.mdxnew file mode 100644index 000000000..63b717a19--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/notification-service.mdx@@ -0,0 +1,339 @@+---+category: SDK+title: Notification Service+description: "Manage notification channels and providers with the openstatus Node.js SDK"+---++Manage notification channels for monitor alerts. Supports 12 providers. The Notification Service provides 7 RPC methods.++## Create Notification++```typescript+import {+ createOpenStatusClient,+ NotificationProvider,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Slack Alerts",+ provider: NotificationProvider.SLACK,+ data: {+ data: {+ case: "slack",+ value: { webhookUrl: "https://hooks.slack.com/services/..." },+ },+ },+ monitorIds: ["mon_123", "mon_456"],+ });++console.log(`Notification created: ${notification?.id}`);+```++The `data` field uses a nested oneof pattern: the outer `data` is the `NotificationData` message, and `data.data` is the oneof that selects the provider-specific configuration. The `case` must match the provider type in lowercase.++## Provider Configurations++Each provider shown as a complete `createNotification` call.++### Slack++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Slack Alerts",+ provider: NotificationProvider.SLACK,+ data: {+ data: {+ case: "slack",+ value: { webhookUrl: "https://hooks.slack.com/services/..." },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Discord++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Discord Alerts",+ provider: NotificationProvider.DISCORD,+ data: {+ data: {+ case: "discord",+ value: { webhookUrl: "https://discord.com/api/webhooks/..." },+ },+ },+ monitorIds: ["mon_123"],+ });+```+++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Email Alerts",+ provider: NotificationProvider.EMAIL,+ data: {+ data: {+ case: "email",+ value: { email: "[email protected]" },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### PagerDuty++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "PagerDuty Alerts",+ provider: NotificationProvider.PAGERDUTY,+ data: {+ data: {+ case: "pagerduty",+ value: { integrationKey: "your-integration-key" },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Opsgenie++```typescript+import { NotificationProvider, OpsgenieRegion } from "@openstatus/sdk-node";++const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Opsgenie Alerts",+ provider: NotificationProvider.OPSGENIE,+ data: {+ data: {+ case: "opsgenie",+ value: { apiKey: "your-api-key", region: OpsgenieRegion.US },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Telegram++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Telegram Alerts",+ provider: NotificationProvider.TELEGRAM,+ data: {+ data: {+ case: "telegram",+ value: { chatId: "123456789" },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Google Chat++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Google Chat Alerts",+ provider: NotificationProvider.GOOGLE_CHAT,+ data: {+ data: {+ case: "googleChat",+ value: { webhookUrl: "https://chat.googleapis.com/v1/spaces/..." },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Grafana OnCall++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Grafana OnCall",+ provider: NotificationProvider.GRAFANA_ONCALL,+ data: {+ data: {+ case: "grafanaOncall",+ value: { webhookUrl: "https://oncall.example.com/..." },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Ntfy++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Ntfy Alerts",+ provider: NotificationProvider.NTFY,+ data: {+ data: {+ case: "ntfy",+ value: {+ topic: "my-alerts",+ serverUrl: "https://ntfy.sh",+ token: "tk_...",+ },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### SMS++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "SMS Alerts",+ provider: NotificationProvider.SMS,+ data: {+ data: {+ case: "sms",+ value: { phoneNumber: "+1234567890" },+ },+ },+ monitorIds: ["mon_123"],+ });+```+++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "WhatsApp Alerts",+ provider: NotificationProvider.WHATSAPP,+ data: {+ data: {+ case: "whatsapp",+ value: { phoneNumber: "+1234567890" },+ },+ },+ monitorIds: ["mon_123"],+ });+```++### Custom Webhook++```typescript+const { notification } = await client.notification.v1.NotificationService+ .createNotification({+ name: "Custom Webhook",+ provider: NotificationProvider.WEBHOOK,+ data: {+ data: {+ case: "webhook",+ value: {+ endpoint: "https://api.example.com/webhook",+ headers: [+ { key: "Authorization", value: "Bearer token" },+ { key: "X-Custom-Header", value: "value" },+ ],+ },+ },+ },+ monitorIds: ["mon_123"],+ });+```++See the [webhook payload reference](/docs/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.++```typescript+import { NotificationProvider } from "@openstatus/sdk-node";++const { success, errorMessage } = await client.notification.v1+ .NotificationService.sendTestNotification({+ provider: NotificationProvider.SLACK,+ data: {+ data: {+ case: "slack",+ value: { webhookUrl: "https://hooks.slack.com/services/..." },+ },+ },+ });++if (success) {+ console.log("Test notification sent successfully");+} else {+ console.log(`Test failed: ${errorMessage}`);+}+```++## Check Notification Limits++Check if the workspace has reached its notification channel limit.++```typescript+const { limitReached, currentCount, maxCount } = await client.notification.v1+ .NotificationService.checkNotificationLimit({});++console.log(`${currentCount}/${maxCount} notification channels used`);+if (limitReached) {+ console.log("Notification limit reached — upgrade your plan");+}+```++## List / Get / Update / Delete Notifications++### List Notifications++```typescript+const { notifications, totalSize } = await client.notification.v1+ .NotificationService.listNotifications({ limit: 10, offset: 0 });++console.log(`Found ${totalSize} notification channels`);+```++### Get Notification++```typescript+import { NotificationProvider } from "@openstatus/sdk-node";++const { notification } = await client.notification.v1.NotificationService+ .getNotification({ id: "notif_123" });++console.log(`Name: ${notification?.name}`);+console.log(`Provider: ${NotificationProvider[notification?.provider ?? 0]}`);+```++### Update Notification++```typescript+const { notification } = await client.notification.v1.NotificationService+ .updateNotification({+ id: "notif_123",+ name: "Updated Slack Alerts",+ monitorIds: ["mon_123", "mon_456", "mon_789"],+ });+```++### Delete Notification++```typescript+const { success } = await client.notification.v1.NotificationService+ .deleteNotification({ id: "notif_123" });+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/overview.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/overview.mdxnew file mode 100644index 000000000..766e89fbe--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/overview.mdx@@ -0,0 +1,48 @@+---+category: SDK+title: Node.js SDK+description: "Interact with openstatus programmatically from your JavaScript and TypeScript applications"+---+++The openstatus Node.js SDK lets you manage monitors, status pages, status reports, maintenance windows, and notifications from JavaScript and TypeScript. Request and response messages are fully typed, generated from the openstatus protobuf schemas.++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).++## Features++- **HTTP, TCP, and DNS monitoring** — monitor websites, APIs, database connections, and DNS records from 28 locations worldwide.+- **Status pages** — create and manage public status pages with monitor-based or static components, grouping, and subscribers.+- **Status reports and maintenance** — manage incident reports with update timelines and schedule planned maintenance windows.+- **Notifications** — configure Slack, Discord, Email, PagerDuty, Opsgenie, Telegram, and webhook channels.+- **Type-safe** — typed request/response messages generated from the openstatus protobuf schemas.+- **Cross-runtime** — works on Node.js, Deno, and Bun, in both ESM and CJS.++## Installation++```bash+npm install @openstatus/sdk-node+```++See [Getting Started](/docs/sdk/nodejs/getting-started) for JSR, Deno, and Bun instructions, a quick start, and a full end-to-end workflow.++## Services++The client exposes one service per domain. Each has its own reference page:++| Service | Page | Purpose |+|---------|------|---------|+| Monitor | [Monitor Service](/docs/sdk/nodejs/monitor-service) | Manage HTTP, TCP, and DNS monitors; trigger checks; read status and summaries. |+| Health | [Health Service](/docs/sdk/nodejs/health-service) | Liveness check for the API. No authentication required. |+| Status Report | [Status Report Service](/docs/sdk/nodejs/status-report-service) | Manage incident reports and their update timelines. |+| Status Page | [Status Page Service](/docs/sdk/nodejs/status-page-service) | Manage status pages, components, component groups, and subscribers. |+| Maintenance | [Maintenance Service](/docs/sdk/nodejs/maintenance-service) | Schedule and manage planned maintenance windows. |+| Notification | [Notification Service](/docs/sdk/nodejs/notification-service) | Configure notification channels and check usage limits. |++For authentication, errors, and TypeScript ergonomics, see [Authentication](/docs/sdk/nodejs/authentication), [Error Handling](/docs/sdk/nodejs/error-handling), [TypeScript Tips](/docs/sdk/nodejs/typescript-tips), and the full [Reference](/docs/sdk/nodejs/reference).++## Resources++- [openstatusHQ/sdk-node on GitHub](https://github.com/openstatusHQ/sdk-node)+- [@openstatus/sdk-node on npm](https://www.npmjs.com/package/@openstatus/sdk-node)+- [API Reference](https://api.openstatus.dev/openapi)diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/reference.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/reference.mdxnew file mode 100644index 000000000..6059737a7--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/reference.mdx@@ -0,0 +1,376 @@+---+category: SDK+title: Reference+description: "Complete reference for enums, regions, assertions, and TypeScript type exports in the openstatus Node.js SDK"+---++## Enums++### Periodicity++| Value | Description |+|-------|-------------|+| `PERIODICITY_30S` | Every 30 seconds |+| `PERIODICITY_1M` | Every 1 minute |+| `PERIODICITY_5M` | Every 5 minutes |+| `PERIODICITY_10M` | Every 10 minutes |+| `PERIODICITY_30M` | Every 30 minutes |+| `PERIODICITY_1H` | Every 1 hour |++### HTTPMethod++| Value | Description |+|-------|-------------|+| `HTTP_METHOD_GET` | GET |+| `HTTP_METHOD_POST` | POST |+| `HTTP_METHOD_HEAD` | HEAD |+| `HTTP_METHOD_PUT` | PUT |+| `HTTP_METHOD_PATCH` | PATCH |+| `HTTP_METHOD_DELETE` | DELETE |+| `HTTP_METHOD_TRACE` | TRACE |+| `HTTP_METHOD_CONNECT` | CONNECT |+| `HTTP_METHOD_OPTIONS` | OPTIONS |++### MonitorStatus++| Value | Description |+|-------|-------------|+| `ACTIVE` | Monitor is healthy |+| `DEGRADED` | Latency threshold exceeded |+| `ERROR` | Monitor is failing |++### TimeRange++| Value | Description |+|-------|-------------|+| `TIME_RANGE_1D` | Last 24 hours |+| `TIME_RANGE_7D` | Last 7 days |+| `TIME_RANGE_14D` | Last 14 days |++### StatusReportStatus++| Value | Description |+|-------|-------------|+| `INVESTIGATING` | Actively investigating the issue |+| `IDENTIFIED` | Root cause has been identified |+| `MONITORING` | Fix deployed, monitoring |+| `RESOLVED` | Issue fully resolved |++### OverallStatus++| Value | Description |+|-------|-------------|+| `OPERATIONAL` | All systems operational |+| `DEGRADED` | Performance is degraded |+| `PARTIAL_OUTAGE` | Some systems are down |+| `MAJOR_OUTAGE` | Major systems are down |+| `MAINTENANCE` | Scheduled maintenance |+| `UNKNOWN` | Status cannot be determined |++### NotificationProvider++| Value | Description |+|-------|-------------|+| `DISCORD` | Discord webhook |+| `EMAIL` | Email notification |+| `GOOGLE_CHAT` | Google Chat webhook |+| `GRAFANA_ONCALL` | Grafana OnCall |+| `NTFY` | Ntfy push service |+| `PAGERDUTY` | PagerDuty |+| `OPSGENIE` | Opsgenie |+| `SLACK` | Slack webhook |+| `SMS` | SMS notification |+| `TELEGRAM` | Telegram bot |+| `WEBHOOK` | Custom webhook |+| `WHATSAPP` | WhatsApp |++### OpsgenieRegion++| Value | Description |+|-------|-------------|+| `US` | US region |+| `EU` | EU region |++### PageAccessType++| Value | Description |+|-------|-------------|+| `PUBLIC` | Publicly accessible |+| `PASSWORD_PROTECTED` | Requires password |+| `AUTHENTICATED` | Requires authentication |++### PageTheme++| Value | Description |+|-------|-------------|+| `SYSTEM` | Follow system theme |+| `LIGHT` | Light theme |+| `DARK` | Dark theme |++### PageComponentType++| Value | Description |+|-------|-------------|+| `MONITOR` | Linked to a monitor |+| `STATIC` | Static component (manual) |++### NumberComparator++| Value | Description |+|-------|-------------|+| `EQUAL` | Equal to target |+| `NOT_EQUAL` | Not equal to target |+| `GREATER_THAN` | Greater than target |+| `GREATER_THAN_OR_EQUAL` | Greater than or equal |+| `LESS_THAN` | Less than target |+| `LESS_THAN_OR_EQUAL` | Less than or equal |++### StringComparator++| Value | Description |+|-------|-------------|+| `CONTAINS` | Contains target string |+| `NOT_CONTAINS` | Does not contain target |+| `EQUAL` | Equal to target |+| `NOT_EQUAL` | Not equal to target |+| `EMPTY` | Value is empty |+| `NOT_EMPTY` | Value is not empty |+| `GREATER_THAN` | Lexicographically greater |+| `GREATER_THAN_OR_EQUAL` | Lexicographically greater than or equal to target |+| `LESS_THAN` | Lexicographically less |+| `LESS_THAN_OR_EQUAL` | Lexicographically less than or equal to target |++### RecordComparator++| Value | Description |+|-------|-------------|+| `EQUAL` | Equal to target |+| `NOT_EQUAL` | Not equal to target |+| `CONTAINS` | Contains target string |+| `NOT_CONTAINS` | Does not contain target |++### ServingStatus++| Value | Description |+|-------|-------------|+| `SERVING` | Service is healthy and serving |+| `NOT_SERVING` | Service is not healthy |++## Regions++Monitor from 28 global locations across multiple providers.++```typescript+import { Region } from "@openstatus/sdk-node";++regions: [Region.FLY_AMS, Region.FLY_IAD, Region.KOYEB_FRA];+```++### Fly.io Regions (18)++| Enum Value | Location |+|------------|----------|+| `FLY_AMS` | Amsterdam |+| `FLY_ARN` | Stockholm |+| `FLY_BOM` | Mumbai |+| `FLY_CDG` | Paris |+| `FLY_DFW` | Dallas |+| `FLY_EWR` | Newark |+| `FLY_FRA` | Frankfurt |+| `FLY_GRU` | São Paulo |+| `FLY_IAD` | Washington D.C. |+| `FLY_JNB` | Johannesburg |+| `FLY_LAX` | Los Angeles |+| `FLY_LHR` | London |+| `FLY_NRT` | Tokyo |+| `FLY_ORD` | Chicago |+| `FLY_SJC` | San Jose |+| `FLY_SIN` | Singapore |+| `FLY_SYD` | Sydney |+| `FLY_YYZ` | Toronto |++### Koyeb Regions (6)++| Enum Value | Location |+|------------|----------|+| `KOYEB_FRA` | Frankfurt |+| `KOYEB_PAR` | Paris |+| `KOYEB_SFO` | San Francisco |+| `KOYEB_SIN` | Singapore |+| `KOYEB_TYO` | Tokyo |+| `KOYEB_WAS` | Washington |++### Railway Regions (4)++| Enum Value | Location |+|------------|----------|+| `RAILWAY_US_WEST2` | US West |+| `RAILWAY_US_EAST4` | US East |+| `RAILWAY_EUROPE_WEST4` | Europe West |+| `RAILWAY_ASIA_SOUTHEAST1` | Asia Southeast |++## Assertions++### Status Code Assertions++Validate HTTP response status codes using `NumberComparator`.++```typescript+import { NumberComparator } from "@openstatus/sdk-node";++statusCodeAssertions: [+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },+ { comparator: NumberComparator.LESS_THAN, target: BigInt(400) },+];+```++### Body Assertions++Validate response body content using `StringComparator`.++```typescript+import { StringComparator } from "@openstatus/sdk-node";++bodyAssertions: [+ { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },+ { comparator: StringComparator.NOT_EMPTY, target: "" },+];+```++### Header Assertions++Validate response headers using `StringComparator` with a header `key`.++```typescript+import { StringComparator } from "@openstatus/sdk-node";++headerAssertions: [+ {+ key: "content-type",+ comparator: StringComparator.CONTAINS,+ target: "application/json",+ },+];+```++### DNS Record Assertions++Validate DNS records using `RecordComparator`. Supported record types: `A`, `AAAA`, `CNAME`, `MX`, `TXT`.++```typescript+import { RecordComparator } from "@openstatus/sdk-node";++recordAssertions: [+ {+ record: "A",+ comparator: RecordComparator.EQUAL,+ target: "93.184.216.34",+ },+ {+ record: "CNAME",+ comparator: RecordComparator.CONTAINS,+ target: "cdn",+ },+];+```++## TypeScript Type Exports++All types and enums exported from `@openstatus/sdk-node`:++### Monitor Types++- `HTTPMonitor`, `Headers`, `OpenTelemetryConfig` — HTTP monitor configuration+- `TCPMonitor` — TCP monitor configuration+- `DNSMonitor` — DNS monitor configuration+- `StatusCodeAssertion`, `BodyAssertion`, `HeaderAssertion`, `RecordAssertion` — assertion types+- `CreateHTTPMonitorRequest`, `CreateHTTPMonitorResponse` — HTTP monitor CRUD+- `CreateTCPMonitorRequest`, `CreateTCPMonitorResponse` — TCP monitor CRUD+- `CreateDNSMonitorRequest`, `CreateDNSMonitorResponse` — DNS monitor CRUD+- `UpdateHTTPMonitorRequest`, `UpdateHTTPMonitorResponse`+- `UpdateTCPMonitorRequest`, `UpdateTCPMonitorResponse`+- `UpdateDNSMonitorRequest`, `UpdateDNSMonitorResponse`+- `ListMonitorsRequest`, `ListMonitorsResponse`+- `DeleteMonitorRequest`, `DeleteMonitorResponse`+- `TriggerMonitorRequest`, `TriggerMonitorResponse`+- `GetMonitorStatusRequest`, `GetMonitorStatusResponse`, `RegionStatus`+- `GetMonitorSummaryRequest`, `GetMonitorSummaryResponse`++### Monitor Enums++- `Periodicity` — check interval+- `Region` — monitoring region+- `MonitorStatus` — active / degraded / error+- `HTTPMethod` — HTTP methods+- `TimeRange` — metrics time range+- `NumberComparator`, `StringComparator`, `RecordComparator` — assertion comparators++### Health Types++- `CheckRequest`, `CheckResponse`+- `ServingStatus` — serving / not serving++### Status Report Types++- `StatusReport`, `StatusReportSummary`, `StatusReportUpdate`+- `CreateStatusReportRequest`, `CreateStatusReportResponse`+- `GetStatusReportRequest`, `GetStatusReportResponse`+- `ListStatusReportsRequest`, `ListStatusReportsResponse`+- `UpdateStatusReportRequest`, `UpdateStatusReportResponse`+- `DeleteStatusReportRequest`, `DeleteStatusReportResponse`+- `AddStatusReportUpdateRequest`, `AddStatusReportUpdateResponse`+- `StatusReportStatus` — investigating / identified / monitoring / resolved++### Status Page Types++- `StatusPage`, `StatusPageSummary`+- `PageComponent`, `PageComponentGroup`+- `PageSubscriber`+- `CreateStatusPageRequest`, `CreateStatusPageResponse`+- `GetStatusPageRequest`, `GetStatusPageResponse`+- `ListStatusPagesRequest`, `ListStatusPagesResponse`+- `UpdateStatusPageRequest`, `UpdateStatusPageResponse`+- `DeleteStatusPageRequest`, `DeleteStatusPageResponse`+- `AddMonitorComponentRequest`, `AddMonitorComponentResponse`+- `AddStaticComponentRequest`, `AddStaticComponentResponse`+- `RemoveComponentRequest`, `RemoveComponentResponse`+- `UpdateComponentRequest`, `UpdateComponentResponse`+- `CreateComponentGroupRequest`, `CreateComponentGroupResponse`+- `DeleteComponentGroupRequest`, `DeleteComponentGroupResponse`+- `UpdateComponentGroupRequest`, `UpdateComponentGroupResponse`+- `SubscribeToPageRequest`, `SubscribeToPageResponse`+- `UnsubscribeFromPageRequest`, `UnsubscribeFromPageResponse`+- `ListSubscribersRequest`, `ListSubscribersResponse`+- `GetStatusPageContentRequest`, `GetStatusPageContentResponse`+- `GetOverallStatusRequest`, `GetOverallStatusResponse`, `ComponentStatus`+- `OverallStatus`, `PageAccessType`, `PageTheme`, `PageComponentType`++### Maintenance Types++- `Maintenance`, `MaintenanceSummary`+- `CreateMaintenanceRequest`, `CreateMaintenanceResponse`+- `GetMaintenanceRequest`, `GetMaintenanceResponse`+- `ListMaintenancesRequest`, `ListMaintenancesResponse`+- `UpdateMaintenanceRequest`, `UpdateMaintenanceResponse`+- `DeleteMaintenanceRequest`, `DeleteMaintenanceResponse`++### Notification Types++- `Notification`, `NotificationSummary`+- `NotificationData`+- `DiscordData`, `EmailData`, `GoogleChatData`, `GrafanaOncallData`, `NtfyData`, `OpsgenieData`, `PagerDutyData`, `SlackData`, `SmsData`, `TelegramData`, `WebhookData`, `WebhookHeader`, `WhatsappData`+- `CreateNotificationRequest`, `CreateNotificationResponse`+- `GetNotificationRequest`, `GetNotificationResponse`+- `ListNotificationsRequest`, `ListNotificationsResponse`+- `UpdateNotificationRequest`, `UpdateNotificationResponse`+- `DeleteNotificationRequest`, `DeleteNotificationResponse`+- `SendTestNotificationRequest`, `SendTestNotificationResponse`+- `CheckNotificationLimitRequest`, `CheckNotificationLimitResponse`+- `NotificationProvider`, `OpsgenieRegion`++### Client Types++- `OpenStatusClient` — client interface+- `OpenStatusClientOptions` — client configuration+- `createOpenStatusClient` — factory function+- `openstatus` — default client instancediff --git a/apps/web/src/content/pages/docs/sdk/nodejs/status-page-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/status-page-service.mdxnew file mode 100644index 000000000..77246cd3b--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/status-page-service.mdx@@ -0,0 +1,225 @@+---+category: SDK+title: Status Page Service+description: "Manage status pages, components, groups, and subscribers with the openstatus Node.js SDK"+---++Manage status pages, components, component groups, and subscribers. The Status Page Service provides 17 RPC methods.++## Status Page CRUD++### Create Status Page++```typescript+const { statusPage } = await client.statusPage.v1.StatusPageService+ .createStatusPage({+ title: "My Service Status",+ slug: "my-service",+ description: "Status page for My Service",+ homepageUrl: "https://example.com",+ contactUrl: "https://example.com/contact",+ });++console.log(`Status page created: ${statusPage?.id}`);+```++### Get Status Page++```typescript+const { statusPage } = await client.statusPage.v1.StatusPageService+ .getStatusPage({ id: "page_123" });+```++### List Status Pages++```typescript+const { statusPages, totalSize } = await client.statusPage.v1.StatusPageService+ .listStatusPages({ limit: 10, offset: 0 });++console.log(`Found ${totalSize} status pages`);+```++### Update Status Page++```typescript+const { statusPage } = await client.statusPage.v1.StatusPageService+ .updateStatusPage({+ id: "page_123",+ title: "Updated Title",+ description: "Updated description",+ });+```++### Delete Status Page++```typescript+const { success } = await client.statusPage.v1.StatusPageService+ .deleteStatusPage({ id: "page_123" });+```++## Components++Components represent individual services on a status page. They can be linked to a monitor (automatically reflects monitor status) or static (manually managed).++### Add Monitor Component++```typescript+const { component } = await client.statusPage.v1.StatusPageService+ .addMonitorComponent({+ pageId: "page_123",+ monitorId: "mon_456",+ name: "API Server",+ description: "Main API endpoint",+ order: 1,+ groupId: "group_789",+ });+```++### Add Static Component++```typescript+const { component } = await client.statusPage.v1.StatusPageService+ .addStaticComponent({+ pageId: "page_123",+ name: "Third-party Service",+ description: "External dependency",+ order: 2,+ });+```++### Update Component++```typescript+const { component } = await client.statusPage.v1.StatusPageService+ .updateComponent({+ id: "comp_123",+ name: "Updated Component Name",+ description: "Updated description",+ order: 3,+ groupId: "group_789",+ groupOrder: 1,+ });+```++### Remove Component++```typescript+const { success } = await client.statusPage.v1.StatusPageService+ .removeComponent({ id: "comp_123" });+```++## Component Groups++Group related components together on a status page.++### Create Component Group++```typescript+const { group } = await client.statusPage.v1.StatusPageService+ .createComponentGroup({+ pageId: "page_123",+ name: "Core Services",+ });+```++### Update Component Group++```typescript+const { group } = await client.statusPage.v1.StatusPageService+ .updateComponentGroup({+ id: "group_123",+ name: "Updated Group Name",+ });+```++### Delete Component Group++```typescript+const { success } = await client.statusPage.v1.StatusPageService+ .deleteComponentGroup({ id: "group_123" });+```++## Subscribers++Manage email subscriptions to status page updates.++### Subscribe to Page++```typescript+const { subscriber } = await client.statusPage.v1.StatusPageService+ .subscribeToPage({+ pageId: "page_123",+ email: "[email protected]",+ });+```++### Unsubscribe from Page++Unsubscribe by email or subscriber ID using the `identifier` oneof:++```typescript+// By email+const { success } = await client.statusPage.v1.StatusPageService+ .unsubscribeFromPage({+ pageId: "page_123",+ identifier: { case: "email", value: "[email protected]" },+ });++// By subscriber ID+const { success: success2 } = await client.statusPage.v1.StatusPageService+ .unsubscribeFromPage({+ pageId: "page_123",+ identifier: { case: "id", value: "sub_456" },+ });+```++### List Subscribers++```typescript+const { subscribers, totalSize } = await client.statusPage.v1.StatusPageService+ .listSubscribers({+ pageId: "page_123",+ limit: 50,+ offset: 0,+ includeUnsubscribed: false,+ });+```++## Get Status Page Content++Get the full content of a status page including components, groups, active status reports, and maintenance windows. Identify the page by ID or slug.++```typescript+const content = await client.statusPage.v1.StatusPageService+ .getStatusPageContent({+ identifier: { case: "slug", value: "my-service" },+ });++console.log(`Page: ${content.statusPage?.title}`);+console.log(`Components: ${content.components.length}`);+console.log(`Groups: ${content.groups.length}`);+console.log(`Active reports: ${content.statusReports.length}`);+console.log(`Maintenances: ${content.maintenances.length}`);+```++## Get Overall Status++Get the aggregated status of a status page and per-component statuses.++```typescript+import { createOpenStatusClient, OverallStatus } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { overallStatus, componentStatuses } = await client.statusPage.v1+ .StatusPageService.getOverallStatus({+ identifier: { case: "id", value: "page_123" },+ });++console.log(`Overall: ${OverallStatus[overallStatus]}`);+for (const { componentId, status } of componentStatuses) {+ console.log(` ${componentId}: ${OverallStatus[status]}`);+}+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/status-report-service.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/status-report-service.mdxnew file mode 100644index 000000000..16d4fa2c6--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/status-report-service.mdx@@ -0,0 +1,105 @@+---+category: SDK+title: Status Report Service+description: "Manage incident reports and status updates with the openstatus Node.js SDK"+---++Manage incident reports with update timelines. The Status Report Service provides 6 RPC methods.++## Create Status Report++```typescript+import {+ createOpenStatusClient,+ StatusReportStatus,+} from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { statusReport } = await client.statusReport.v1.StatusReportService+ .createStatusReport({+ title: "API Degradation",+ status: StatusReportStatus.INVESTIGATING,+ message: "We are investigating reports of increased latency.",+ date: "2024-01-15T10:30:00Z",+ pageId: "page_123",+ pageComponentIds: ["comp_456"],+ notify: true,+ });++console.log(`Status report created: ${statusReport?.id}`);+```++## Add Status Report Update++Add a new entry to a status report's timeline.++```typescript+import { StatusReportStatus } from "@openstatus/sdk-node";++const { statusReport } = await client.statusReport.v1.StatusReportService+ .addStatusReportUpdate({+ statusReportId: "sr_123",+ status: StatusReportStatus.IDENTIFIED,+ message: "The issue has been identified as a database connection problem.",+ date: "2024-01-15T11:00:00Z",+ notify: true,+ });+```++## List Status Reports++List status reports with optional status filtering and pagination.++```typescript+import { StatusReportStatus } from "@openstatus/sdk-node";++const { statusReports, totalSize } = await client.statusReport.v1+ .StatusReportService.listStatusReports({+ limit: 10,+ offset: 0,+ statuses: [StatusReportStatus.INVESTIGATING, StatusReportStatus.IDENTIFIED],+ });++console.log(`Found ${totalSize} status reports`);+```++## Get / Update / Delete Status Reports++### Get Status Report++Returns the full report including the updates timeline.++```typescript+import { StatusReportStatus } from "@openstatus/sdk-node";++const { statusReport } = await client.statusReport.v1.StatusReportService+ .getStatusReport({ id: "sr_123" });++console.log(`Title: ${statusReport?.title}`);+console.log(`Status: ${StatusReportStatus[statusReport?.status ?? 0]}`);++for (const update of statusReport?.updates ?? []) {+ console.log(` ${update.date}: [${StatusReportStatus[update.status]}] ${update.message}`);+}+```++### Update Status Report++```typescript+const { statusReport } = await client.statusReport.v1.StatusReportService+ .updateStatusReport({+ id: "sr_123",+ title: "Updated Title",+ pageComponentIds: ["comp_456", "comp_789"],+ });+```++### Delete Status Report++```typescript+const { success } = await client.statusReport.v1.StatusReportService+ .deleteStatusReport({ id: "sr_123" });+```diff --git a/apps/web/src/content/pages/docs/sdk/nodejs/typescript-tips.mdx b/apps/web/src/content/pages/docs/sdk/nodejs/typescript-tips.mdxnew file mode 100644index 000000000..9cb125c6c--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/nodejs/typescript-tips.mdx@@ -0,0 +1,155 @@+---+category: SDK+title: TypeScript Tips+description: "Tips for working with bigint fields, oneof types, and migrating clients in the openstatus Node.js SDK"+---++## Working with bigint Fields++Protocol Buffers `int64` fields map to `bigint` in TypeScript. This affects:++- **Monitor configuration**: `timeout`, `retry`, `degradedAt`+- **Assertions**: `StatusCodeAssertion.target`+- **Monitor summary**: `totalSuccessful`, `totalDegraded`, `totalFailed`, `p50`, `p75`, `p90`, `p95`, `p99`++Use `BigInt()` to create values:++```typescript+const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({+ monitor: {+ name: "My API",+ url: "https://example.com",+ periodicity: Periodicity.PERIODICITY_1M,+ active: true,+ timeout: BigInt(30000), // 30 seconds+ retry: BigInt(5), // 5 retries+ degradedAt: BigInt(3000), // degraded after 3s+ statusCodeAssertions: [+ { comparator: NumberComparator.EQUAL, target: BigInt(200) },+ ],+ },+});+```++Reading bigint values:++```typescript+const summary = await client.monitor.v1.MonitorService.getMonitorSummary({+ id: "mon_123",+ timeRange: TimeRange.TIME_RANGE_7D,+ regions: [],+});++// bigint values — use Number() for display if values are safe+console.log(`P95 latency: ${summary.p95}ms`);+console.log(`Total checks: ${summary.totalSuccessful + summary.totalDegraded + summary.totalFailed}`);+```++## Handling oneof Types++Several responses use protobuf `oneof` fields, which map to discriminated unions in TypeScript.++### MonitorConfig (getMonitor)++```typescript+const { monitor } = await client.monitor.v1.MonitorService.getMonitor({+ id: "mon_123",+});++switch (monitor?.config.case) {+ case "http":+ // monitor.config.value is HTTPMonitor+ console.log(`URL: ${monitor.config.value.url}`);+ break;+ case "tcp":+ // monitor.config.value is TCPMonitor+ console.log(`URI: ${monitor.config.value.uri}`);+ break;+ case "dns":+ // monitor.config.value is DNSMonitor+ console.log(`Domain: ${monitor.config.value.uri}`);+ break;+}+```++### NotificationData (createNotification)++The `data.data` field selects the provider-specific configuration:++```typescript+// The case string matches the provider in camelCase+data: {+ data: { case: "slack", value: { webhookUrl: "..." } }+}+data: {+ data: { case: "googleChat", value: { webhookUrl: "..." } }+}+data: {+ data: { case: "grafanaOncall", value: { webhookUrl: "..." } }+}+```++### Status Page Identifiers++`getStatusPageContent` and `getOverallStatus` accept a page identifier by ID or slug:++```typescript+// By ID+{ identifier: { case: "id", value: "page_123" } }++// By slug+{ identifier: { case: "slug", value: "my-service" } }+```++### Unsubscribe Identifier++`unsubscribeFromPage` accepts an email or subscriber ID:++```typescript+// By email+{ identifier: { case: "email", value: "[email protected]" } }++// By subscriber ID+{ identifier: { case: "id", value: "sub_456" } }+```++## Migrating from Default Client to createOpenStatusClient++**Before** — manual headers on every call:++```typescript+import { openstatus } from "@openstatus/sdk-node";++const headers = { "x-openstatus-key": process.env.OPENSTATUS_API_KEY };++const { httpMonitors } = await openstatus.monitor.v1.MonitorService+ .listMonitors({}, { headers });++const { monitor } = await openstatus.monitor.v1.MonitorService+ .createHTTPMonitor({+ monitor: { name: "API", url: "https://example.com", periodicity: 2, active: true },+ }, { headers });+```++**After** — configure once, use everywhere:++```typescript+import { createOpenStatusClient, Periodicity } from "@openstatus/sdk-node";++const client = createOpenStatusClient({+ apiKey: process.env.OPENSTATUS_API_KEY,+});++const { httpMonitors } = await client.monitor.v1.MonitorService+ .listMonitors({});++const { monitor } = await client.monitor.v1.MonitorService+ .createHTTPMonitor({+ monitor: {+ name: "API",+ url: "https://example.com",+ periodicity: Periodicity.PERIODICITY_1M,+ active: true,+ },+ });+```diff --git a/apps/web/src/content/pages/docs/sdk/php/overview.mdx b/apps/web/src/content/pages/docs/sdk/php/overview.mdxnew file mode 100644index 000000000..ec2fb3144--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/php/overview.mdx@@ -0,0 +1,277 @@+---+category: SDK+title: PHP SDK+description: "Interact with openstatus programmatically from your PHP applications"+---+++The openstatus PHP SDK lets you manage monitors, status pages, status reports, maintenance windows, and notifications directly from your PHP applications. Request and response messages are strongly typed, generated from the openstatus protobuf schemas.++The SDK is open source and developed in its own repository, [openstatusHQ/sdk-php](https://github.com/openstatusHQ/sdk-php), and published on [Packagist](https://packagist.org/packages/openstatus/sdk-php).++## Features++- **HTTP, TCP, and DNS monitoring** — monitor websites, APIs, database connections, and DNS records from 28 locations worldwide.+- **Status pages** — create and manage public status pages with monitor-based or static components, grouping, and subscribers.+- **Status reports and maintenance** — manage incident reports with update timelines and schedule planned maintenance windows.+- **Notifications** — configure Slack, Discord, Email, PagerDuty, Opsgenie, Telegram, and webhook channels.+- **Type-safe** — strongly-typed messages generated from the openstatus protobuf schemas; no proto toolchain needed.+- **PSR-18 transport** — bring your own HTTP client, or use the bundled Guzzle implementation.++## Get Your API Key++Before using the SDK, you need an API key:++1. Log in to the [openstatus dashboard](https://www.openstatus.dev/app/login)+2. Go to **Settings** > **API Keys**+3. Click **Create API Key** and copy it++<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>++## Installation++Requires PHP 8.4 or later.++```bash+composer require openstatus/sdk-php+```++## Quick Start++```php+<?php++require __DIR__ . '/vendor/autoload.php';++use Openstatus\Monitor\V1\CreateHTTPMonitorRequest;+use Openstatus\Monitor\V1\HTTPMethod;+use Openstatus\Monitor\V1\HTTPMonitor;+use Openstatus\Monitor\V1\ListMonitorsRequest;+use Openstatus\Monitor\V1\NumberComparator;+use Openstatus\Monitor\V1\Periodicity;+use Openstatus\Monitor\V1\Region;+use Openstatus\Monitor\V1\StatusCodeAssertion;+use Openstatus\Sdk\ClientOptions;+use Openstatus\Sdk\OpenstatusClient;++$client = new OpenstatusClient(new ClientOptions(+ apiKey: getenv('OPENSTATUS_API_KEY') ?: null,+));++// Create a monitor+$response = $client->monitor->v1->monitorService->createHTTPMonitor(+ new CreateHTTPMonitorRequest([+ 'monitor' => new HTTPMonitor([+ 'name' => 'My API',+ 'url' => 'https://api.example.com/health',+ 'periodicity' => Periodicity::PERIODICITY_1M,+ 'method' => HTTPMethod::HTTP_METHOD_GET,+ 'regions' => [+ Region::REGION_FLY_AMS,+ Region::REGION_FLY_IAD,+ Region::REGION_FLY_SYD,+ ],+ 'active' => true,+ 'status_code_assertions' => [+ new StatusCodeAssertion([+ 'comparator' => NumberComparator::NUMBER_COMPARATOR_EQUAL,+ 'target' => 200,+ ]),+ ],+ ]),+ ]),+);++$monitor = $response->getMonitor();+printf("Monitor created: %s\n", $monitor?->getId() ?? 'unknown');++// List all monitors+$list = $client->monitor->v1->monitorService->listMonitors(new ListMonitorsRequest());+printf("Found %d monitors\n", $list->getTotalSize());+```++## Authentication++All API requests require an API key. Configure the client once and every service call reuses it:++```php+use Openstatus\Sdk\ClientOptions;+use Openstatus\Sdk\OpenstatusClient;++$client = new OpenstatusClient(new ClientOptions(+ apiKey: getenv('OPENSTATUS_API_KEY') ?: null,+));+```++If `apiKey` is not passed in `ClientOptions`, the SDK falls back to the `OPENSTATUS_API_KEY` environment variable. The same applies to `baseUrl` / `OPENSTATUS_API_URL`.++| Variable | Description | Default |+|----------------------|-------------------------|----------------------------------|+| `OPENSTATUS_API_KEY` | Your openstatus API key | Required for authenticated calls |+| `OPENSTATUS_API_URL` | Custom API endpoint | `https://api.openstatus.dev` |++Every service method also accepts an optional array of headers as a second argument, merged into the request — useful for tracing IDs or one-off overrides:++```php+$client->monitor->v1->monitorService->listMonitors(+ new ListMonitorsRequest(),+ ['x-trace-id' => 'trace-abc'],+);+```++## Services++The client exposes one service per domain. All examples below assume:++```php+$client = new OpenstatusClient(new ClientOptions(+ apiKey: getenv('OPENSTATUS_API_KEY') ?: null,+));+```++| Service | Accessor | Purpose |+|---------|----------|---------|+| Monitor | `$client->monitor->v1->monitorService` | Manage HTTP, TCP, and DNS monitors; trigger checks; read status, summaries, and response logs. |+| Health | `$client->health->v1->healthService` | Liveness check for the API. No authentication required. |+| Status Report | `$client->statusReport->v1->statusReportService` | Manage incident reports and their update timelines. |+| Status Page | `$client->statusPage->v1->statusPageService` | Manage status pages, components, component groups, and subscribers. |+| Maintenance | `$client->maintenance->v1->maintenanceService` | Schedule and manage planned maintenance windows. |+| Notification | `$client->notification->v1->notificationService` | Configure notification channels and check usage limits. |++### Creating a monitor with assertions++Assertions are evaluated against each check response. All matching assertions must pass for a check to be successful.++```php+use Openstatus\Monitor\V1\BodyAssertion;+use Openstatus\Monitor\V1\HeaderAssertion;+use Openstatus\Monitor\V1\NumberComparator;+use Openstatus\Monitor\V1\StatusCodeAssertion;+use Openstatus\Monitor\V1\StringComparator;++$statusCode = new StatusCodeAssertion([+ 'comparator' => NumberComparator::NUMBER_COMPARATOR_EQUAL,+ 'target' => 200,+]);++$body = new BodyAssertion([+ 'comparator' => StringComparator::STRING_COMPARATOR_CONTAINS,+ 'target' => 'ok',+]);++$header = new HeaderAssertion([+ 'key' => 'content-type',+ 'comparator' => StringComparator::STRING_COMPARATOR_EQUAL,+ 'target' => 'application/json',+]);+```++### Creating a status page++```php+use Openstatus\Status_page\V1\CreateStatusPageRequest;+use Openstatus\Status_page\V1\PageTheme;+use Openstatus\Status_page\V1\StatusPage;++$client->statusPage->v1->statusPageService->createStatusPage(new CreateStatusPageRequest([+ 'page' => new StatusPage([+ 'title' => 'Acme Status',+ 'slug' => 'acme',+ 'theme' => PageTheme::PAGE_THEME_LIGHT,+ ]),+]));+```++## Working with enums++All enums emitted by the protobuf compiler are plain classes with `const int` values. Getters return `int`; use the static `name()` helper to convert to a string.++```php+use Openstatus\Monitor\V1\HTTPMethod;+use Openstatus\Monitor\V1\Periodicity;++HTTPMethod::HTTP_METHOD_GET; // int 1+HTTPMethod::name(HTTPMethod::HTTP_METHOD_GET); // "HTTP_METHOD_GET"+Periodicity::PERIODICITY_1M; // int 2+```++<Aside type="note">int64 fields (timestamps, percentiles, nanosecond latencies) may return `int|string` from getters because the generator falls back to strings on 32-bit platforms. On 64-bit PHP the value is always an `int`. Cast with `(int)` if you need to be safe across both platforms.</Aside>++## Error Handling++All Connect RPC errors raise `Openstatus\Sdk\Exception\OpenstatusException` or a subclass. The exception carries the Connect error code, HTTP status, parsed `details` array, and raw response body.++```php+use Openstatus\Sdk\Exception\AuthenticationException;+use Openstatus\Sdk\Exception\InvalidArgumentException;+use Openstatus\Sdk\Exception\NotFoundException;+use Openstatus\Sdk\Exception\OpenstatusException;+use Openstatus\Sdk\Exception\RateLimitException;++try {+ $client->monitor->v1->monitorService->createHTTPMonitor($req);+} catch (AuthenticationException $e) {+ // 401 / "unauthenticated"+} catch (NotFoundException $e) {+ // 404 / "not_found"+} catch (InvalidArgumentException $e) {+ // 400 / "invalid_argument" — inspect $e->details() for field violations+ foreach ($e->details() as $detail) {+ printf("%s: %s\n", $detail->type, $detail->value);+ }+} catch (RateLimitException $e) {+ // 429 / "resource_exhausted"+} catch (OpenstatusException $e) {+ printf("code=%s http=%d body=%s\n", $e->connectCode(), $e->httpStatus(), $e->rawBody());+}+```++## Framework Integration++### Symfony++Register the client as a service in `config/services.yaml`:++```yaml+services:+ Openstatus\Sdk\ClientOptions:+ arguments:+ $apiKey: '%env(OPENSTATUS_API_KEY)%'++ Openstatus\Sdk\OpenstatusClient:+ arguments:+ $options: '@Openstatus\Sdk\ClientOptions'+```++Then inject `OpenstatusClient` into any controller or service.++### Laravel++In a service provider's `register()` method:++```php+$this->app->singleton(\Openstatus\Sdk\OpenstatusClient::class, function (): \Openstatus\Sdk\OpenstatusClient {+ return new \Openstatus\Sdk\OpenstatusClient(new \Openstatus\Sdk\ClientOptions(+ apiKey: env('OPENSTATUS_API_KEY'),+ ));+});+```++Resolve it from the container with `app(\Openstatus\Sdk\OpenstatusClient::class)`.++### Custom PSR-18 client++Bring your own HTTP client (Symfony HttpClient, Saloon, Mock, etc.) — anything implementing `Psr\Http\Client\ClientInterface`:++```php+$client = new OpenstatusClient(new ClientOptions(+ apiKey: getenv('OPENSTATUS_API_KEY') ?: null,+ httpClient: $myPsr18Client,+));+```++## Resources++- [openstatusHQ/sdk-php on GitHub](https://github.com/openstatusHQ/sdk-php)+- [openstatus/sdk-php on Packagist](https://packagist.org/packages/openstatus/sdk-php)+- [API Reference](https://api.openstatus.dev/openapi)diff --git a/apps/web/src/content/pages/docs/sdk/python/overview.mdx b/apps/web/src/content/pages/docs/sdk/python/overview.mdxnew file mode 100644index 000000000..6a1bf1735--- /dev/null+++ b/apps/web/src/content/pages/docs/sdk/python/overview.mdx@@ -0,0 +1,211 @@+---+category: SDK+title: Python SDK+description: "Interact with openstatus programmatically from your Python applications"+---+++The openstatus Python SDK lets you manage monitors, status pages, status reports, maintenance windows, and notifications from Python code, scripts, and automations. It ships both synchronous and asynchronous clients with identical, fully typed method signatures.++The SDK is open source and developed in its own repository, [openstatusHQ/sdk-python](https://github.com/openstatusHQ/sdk-python), and published on [PyPI](https://pypi.org/project/openstatus/).++## Features++- **HTTP, TCP, and DNS monitoring** — monitor websites, APIs, database connections, and DNS records from 28 locations worldwide.+- **Status pages** — create and manage public status pages with monitor-based or static components, grouping, and subscribers.+- **Status reports and maintenance** — manage incident reports with update timelines and schedule planned maintenance windows.+- **Notifications** — configure Slack, Discord, Email, PagerDuty, Opsgenie, Telegram, and webhook channels.+- **Sync and async** — `OpenstatusClient` and `AsyncOpenstatusClient` share the same API surface.+- **Type-safe** — typed request/response messages generated from the openstatus protobuf schemas.++## Get Your API Key++Before using the SDK, you need an API key:++1. Log in to the [openstatus dashboard](https://www.openstatus.dev/app/login)+2. Go to **Settings** > **API Keys**+3. Click **Create API Key** and copy it++<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>++## Installation++Requires Python 3.10 or later.++```bash+pip install openstatus+# or+uv add openstatus+```++## Authentication++Authentication uses the `OPENSTATUS_API_KEY` environment variable by default:++```bash+export OPENSTATUS_API_KEY="your-key-here"+```++Alternatively, pass credentials programmatically:++```python+from openstatus import ClientOptions, OpenstatusClient++client = OpenstatusClient(ClientOptions(api_key="your-key"))+```++## Quick Start++The SDK offers both synchronous and asynchronous clients with identical method signatures.++**Sync:**++```python+from openstatus import OpenstatusClient+from openstatus._gen.openstatus.health.v1.health_pb2 import CheckRequest++with OpenstatusClient() as client:+ health = client.health.v1.HealthService.check(CheckRequest())+ print(health.status)+```++**Async:**++```python+import asyncio+from openstatus import AsyncOpenstatusClient+from openstatus._gen.openstatus.health.v1.health_pb2 import CheckRequest++async def main():+ async with AsyncOpenstatusClient() as client:+ health = await client.health.v1.HealthService.check(CheckRequest())+ print(health.status)++asyncio.run(main())+```++## Services++The SDK covers six primary services with typed request/response objects.++| Service | Accessor | Purpose |+|---------|----------|---------|+| Monitor | `client.monitor.v1.MonitorService` | Manage HTTP, TCP, and DNS monitors; trigger checks; read status and summaries. |+| Health | `client.health.v1.HealthService` | Liveness check for the API. No authentication required. |+| Status Report | `client.status_report.v1.StatusReportService` | Manage incident reports and their update timelines. |+| Status Page | `client.status_page.v1.StatusPageService` | Manage status pages, components, component groups, and subscribers. |+| Maintenance | `client.maintenance.v1.MaintenanceService` | Schedule and manage planned maintenance windows. |+| Notification | `client.notification.v1.NotificationService` | Configure notification channels and check usage limits. |++### Monitors++```python+from openstatus._gen.openstatus.monitor.v1.service_pb2 import (+ ListMonitorsRequest,+ GetMonitorRequest,+ TriggerMonitorRequest,+)++client.monitor.v1.MonitorService.list_monitors(ListMonitorsRequest())+client.monitor.v1.MonitorService.get_monitor(GetMonitorRequest(id="abc"))+client.monitor.v1.MonitorService.trigger_monitor(TriggerMonitorRequest(id="abc"))+```++### Status pages, reports, and maintenance++```python+from openstatus._gen.openstatus.status_report.v1.service_pb2 import ListStatusReportsRequest+from openstatus._gen.openstatus.status_page.v1.service_pb2 import ListStatusPagesRequest+from openstatus._gen.openstatus.maintenance.v1.service_pb2 import ListMaintenancesRequest++client.status_report.v1.StatusReportService.list_status_reports(ListStatusReportsRequest())+client.status_page.v1.StatusPageService.list_status_pages(ListStatusPagesRequest())+client.maintenance.v1.MaintenanceService.list_maintenances(ListMaintenancesRequest())+```++### Notifications++```python+from openstatus._gen.openstatus.notification.v1.service_pb2 import ListNotificationsRequest++client.notification.v1.NotificationService.list_notifications(ListNotificationsRequest())+```++## Advanced Configuration++Customize HTTP behavior by passing your own `httpx` client:++```python+import httpx+from openstatus import ClientOptions, OpenstatusClient++http = httpx.Client(+ timeout=httpx.Timeout(connect=2.0, read=10.0, write=10.0, pool=10.0),+ transport=httpx.HTTPTransport(retries=3),+)+client = OpenstatusClient(ClientOptions(http_client=http))+```++## Error Handling++The SDK provides a typed exception hierarchy for different failure scenarios:++```python+from openstatus import (+ AuthenticationError,+ NotFoundError,+ OpenstatusError,+ OpenstatusClient,+)++try:+ result = client.monitor.v1.MonitorService.get_monitor(request)+except NotFoundError as err:+ print(f"Not found: {err.http_status}")+except AuthenticationError:+ print("Invalid credentials")+except OpenstatusError as err:+ print(f"Error: {err.connect_code}")+```++## Framework Integration++### FastAPI++```python+from fastapi import Depends, FastAPI+from openstatus import OpenstatusClient++app = FastAPI()+_client = OpenstatusClient()++def get_client() -> OpenstatusClient:+ return _client+[email protected]_event("shutdown")+def shutdown():+ _client.close()+```++### Django++```python+from django.conf import settings+from openstatus import ClientOptions, OpenstatusClient++_singleton = None++def client() -> OpenstatusClient:+ global _singleton+ if _singleton is None:+ _singleton = OpenstatusClient(+ ClientOptions(api_key=settings.OPENSTATUS_API_KEY)+ )+ return _singleton+```++## Resources++- [openstatusHQ/sdk-python on GitHub](https://github.com/openstatusHQ/sdk-python)+- [openstatus on PyPI](https://pypi.org/project/openstatus/)+- [API Reference](https://api.openstatus.dev/openapi)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.mdxnew file mode 100644index 000000000..7fc8949b4--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/get-started-with-openstatus-cli.mdx@@ -0,0 +1,183 @@+---+category: Tutorials+title: Get Started with openstatus CLI+description: "Step-by-step tutorial to install and use the openstatus CLI for monitoring as code"+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~10 minutes |+| **Level** | Intermediate |+| **Prerequisites** | openstatus account, command line experience |++In this tutorial, you'll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.++### Prerequisites++- An openstatus account+- Command line experience+- API token from your openstatus workspace (Settings → API)++### What you'll build++By the end of this tutorial, you'll have:+- openstatus CLI installed on your system+- Monitors exported to a YAML configuration file+- Understanding of monitoring as code workflows+- Ability to manage monitors programmatically++<Image+ src="/docs/tutorial/get-started-with-openstatus-cli/CLI.png"+ alt="openstatus CLI in action showing monitor management"+/>++## Installation++Install the openstatus CLI to manage your monitors directly from code.++### macOS++Using Homebrew (recommended):+```bash+brew install openstatusHQ/cli/openstatus --cask+```++Or using the install script:+```bash+curl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.sh | bash+```++### Linux++```bash+curl -fsSL https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.sh | bash+```++### Windows++```powershell+iwr https://raw.githubusercontent.com/openstatusHQ/cli/refs/heads/main/install.ps1 | iex+```++### Verify installation++Run the following command to confirm the CLI is installed:++```bash+openstatus --version+```++You should see output like:++```+openstatus version x.x.x+```++## Configure API authentication++Create an API key in your workspace settings (Settings → API), then set it as an environment variable:++```bash+# macOS / Linux+export OPENSTATUS_API_TOKEN=<your-api-token>+```++```powershell+# Windows PowerShell+$env:OPENSTATUS_API_TOKEN="<your-api-token>"+```++<Aside>Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.</Aside>++## Import existing monitors++Start by importing your existing monitors from your workspace to a YAML file:++```bash+openstatus monitors import+```++You should see output confirming the import:++```+Successfully imported X monitors to openstatus.yaml+```++This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.++**Checkpoint:** Open the `openstatus.yaml` file and verify it contains your monitors. You should see entries with your monitor names and URLs.++## Manage monitors as code++Now you can add, remove, or update monitors in the YAML file and apply your changes:++```bash+openstatus monitors apply+```++The CLI will show you a diff of changes before applying them, ensuring you're aware of what will be modified.++## What you've accomplished++Excellent work! You've successfully:+- ✅ Installed the openstatus CLI+- ✅ Configured API authentication+- ✅ Imported monitors to a YAML file+- ✅ Learned the monitoring as code workflow++## Troubleshooting++### "command not found: openstatus"++**Cause:** The CLI binary is not in your PATH.++**Fix (macOS/Homebrew):**+```bash+brew reinstall openstatusHQ/cli/openstatus --cask+```++**Fix (install script):** Ensure `~/.local/bin` is in your PATH:+```bash+export PATH="$HOME/.local/bin:$PATH"+```++### "unauthorized" or "invalid token" error++**Cause:** Your API token is missing or incorrect.++**Fix:**+1. Verify the token is set: `echo $OPENSTATUS_API_TOKEN`+2. Regenerate the token in your workspace settings (Settings → API)+3. Make sure there are no extra spaces or newlines in the token value++### "no monitors found" on import++**Cause:** Your workspace has no monitors, or the token belongs to a different workspace.++**Fix:** Create at least one monitor in the dashboard first, then retry the import.++## What's next?++Now that you have the CLI set up, you can:++- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Example of CLI-based monitor configuration+- **[CLI Reference](/docs/reference/cli-reference)** - Complete command documentation+- **[Set up CI/CD](/docs/guides/how-to-run-synthetic-test-github-action)** - Automate monitoring in your pipeline++### Advanced workflows++With the CLI, you can:+- Version control your monitoring configuration with Git+- Review monitoring changes in pull requests+- Automate monitor creation for new services+- Sync monitors across multiple environments+- Implement GitOps for infrastructure monitoring++## 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 configurationsdiff --git a/apps/web/src/content/pages/docs/tutorial/getting-started.mdx b/apps/web/src/content/pages/docs/tutorial/getting-started.mdxnew file mode 100644index 000000000..74fb156a0--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/getting-started.mdx@@ -0,0 +1,41 @@+---+category: Tutorials+title: Tutorials Overview+description: "Step-by-step tutorials to create monitors, status pages, and private locations with openstatus."+sidebar:+ label: Tutorials Overview+ order: 1+---++## Tutorials++### What you'll learn++Our tutorials are designed to help you:+- Get your first monitor up and running+- Create and configure status pages+- Set up monitoring infrastructure+- Use openstatus CLI for automation++### Core Tutorials++Start your journey with openstatus:++- **[Create Your First Monitor](/docs/tutorial/how-to-create-monitor)** (~5 min) - Learn the fundamentals by setting up uptime monitoring for your first endpoint+- **[Create a Status Page](/docs/tutorial/how-to-create-status-page)** (~5 min) - Build a public status page to communicate service health to your users+- **[Configure Your Status Page](/docs/tutorial/how-to-configure-status-page)** (~10 min) - Customize your status page with monitors, domains, and protection+- **[Set Up the Slack Agent](/docs/tutorial/how-to-setup-slack-agent)** (~5 min) - Manage incidents directly from Slack++### Advanced Tutorials++Once you're comfortable with the basics:++- **[Create a Private Location (Beta)](/docs/tutorial/how-to-create-private-location)** (~15 min) - Set up monitoring from your own infrastructure+- **[Get Started with openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli)** (~10 min) - Automate monitor management with our command-line tool++### What's next?++After completing these tutorials, you'll be ready to:+- Explore [how-to guides](/docs/guides/getting-started) for specific tasks and advanced scenarios+- Dive into [explanations](/docs/concept/getting-started) to understand the concepts behind the features+- Reference our [technical documentation](/docs/reference/cli-reference) for detailed specificationsdiff --git a/apps/web/src/content/pages/docs/tutorial/how-to-configure-status-page.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-configure-status-page.mdxnew file mode 100644index 000000000..0fa716944--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-configure-status-page.mdx@@ -0,0 +1,168 @@+---+category: Tutorials+title: Configure Your Status Page+description: "A step-by-step tutorial to customize and configure your status page"+---++++## What you'll learn++In this tutorial, you'll learn how to customize your status page's appearance and behavior. You'll explore different display options, themes, and configuration settings to create a status page that matches your brand and communication style.++### Prerequisites++- An openstatus account+- A status page already created (see [Create a Status Page](/docs/tutorial/how-to-create-status-page))+- At least one monitor added to your status page++### What you'll build++By the end of this tutorial, you'll have:+- A customized status page with your preferred theme+- Configured status trackers displaying data your way+- Links to important resources+- Multi-language support with a locale switcher+- Preview and live configuration experience++## Status Page Customization++openstatus offers enhanced status page customization with multiple themes and display options.++Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)++## Get started++Go to the **Status Page Redesign** section in your status page settings and toggle `Enable New Version`. Once enabled, you'll see three subsections:++1. **Tracker Configuration**+2. **Theme Explorer**+3. **Links**++<Image+ src="/docs/tutorial/configure-status-page/configure-status-page-1.png"+ alt="Create your status page"+/>++### View and configure status page++Before choosing to enable the new page, we provide you with a way to check the configuration first. Click on the **View and configure status page** and you'll get forwarded to your status page and a bottom right floating button will appear. Once you're done, click on the **Dashboard** and you'll be forwarded to your page where you get asked to save the config before continuing.++<Image+ src="/docs/tutorial/configure-status-page/status-page-floating.png"+ alt="Status page floating configuration popover"+/>+++---++<Aside>Once enabled, the subdomain will have a rewrite to the new project. We are adding a `maxAge: 600` request cookie to improve the page load. **If you decide to deactivate the new version, it might take up to 10 minutes for the user to see the old page.**</Aside>++### 1. Tracker Configuration++We have three new status tracker configurations to provide you with a maximum choice of displaying the collected data.++**Bar Type**: How every 'day' is displayed in for a status tracker. Either **absolute** or **manual**.++**Card Type**: The card type is only configurable if the bar type is **absolute**. You'll then be able to choose between **duration**, which will show the duration of "success", "error", "degraded" or "maintenance" reports or **requests** where we will share the number of request status itself. If **manual** bar type is chosen, we will only show the most significant status of the day.++**Show Uptime**: The uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports.++A few examples to understand it:++Example of **absolute bar** with **duration card** and **showing uptime**++<Image+ src="/docs/tutorial/configure-status-page/status-page-beta-3.png"+ alt="absolute bar type with duration card and showing uptime"+/>++Example of **absolute bar** with **request card** and **hiding uptime**++<Image+ src="/docs/tutorial/configure-status-page/status-page-beta-4.png"+ alt="absolute bar type with request card and hiding uptime"+/>++Example of **manual bar** with **simple card** and **hiding uptime**++<Image+ src="/docs/tutorial/configure-status-page/status-page-beta-2.png"+ alt="manual bar type and hiding uptime"+/>++### 2. Theme Explorer++You can choose between different themes. We start with the following three:++- `default` (openstatus)+- `supabase`+- `github-high-contrast`++Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. If you want, you can contribute your own to the list.++If you use AI agents, install the [`openstatus-theme` skill](https://github.com/openstatusHQ/skills/tree/main/skills/openstatus-theme) with `npx skills add openstatushq/skills --skill openstatus-theme` to get guided help through palette design, accessibility checks, file scaffolding, and PR submission.++### 3. Links++Let's have a closer look at your status page header navigation:++<Image+ src="/docs/tutorial/configure-status-page/status-page-beta-1.png"+ alt="Header navigation of your status page"+/>++**Homepage URL**: Your logo will support linking to your own website.++**Contact URL**: If filled out, you will see a `Message` icon that users can click to forward them to a contact page. This can also be an email client by starting the input with `mailto:` (e.g. `mailto:[email protected]`).++---++### 4. Locales++You can offer your status page in multiple languages. In the **Locales** section of your status page settings:++1. Choose a **Default Locale** — the fallback language for visitors.+2. Enable the **Locale Switcher** to let visitors pick their preferred language.+3. Select which languages to make available.++Currently supported: English, French, and German. See [How to translate your status page](/docs/guides/how-to-translate-status-page) for details on contributing new translations.++---++We are continuously adding new features. Feel free to let us know what's missing!++## What you've accomplished++Excellent work! You've successfully:+- ✅ Enabled and configured the new status page design+- ✅ Customized status tracker display options+- ✅ Explored and applied theme settings+- ✅ Added navigation links to your status page+- ✅ Configured locales and the language switcher+- ✅ Previewed changes before making them live++## What's next?++Now that your status page is configured, you can:++- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** - Learn effective incident communication+- **[Add Status Subscribers](/docs/reference/subscriber)** - Let users subscribe to updates++### Learn more++- **[Status Page Reference](/docs/reference/status-page)** - Complete configuration options+- **[Uptime Calculation Values](/docs/concept/uptime-calculation-and-values)** - How uptime percentages work+++## Video Tutorial++<ShowcaseYouTube+ entries={[+ {+ href: 'https://www.youtube.com/watch?v=igMbSrej6RQ',+ title: 'View, configure and enable the new status page',+ },++ ]}+/>diff --git a/apps/web/src/content/pages/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdxnew file mode 100644index 000000000..84ce5effe--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-connect-openstatus-to-claude-code.mdx@@ -0,0 +1,139 @@+---+category: Tutorials+title: Connect openstatus to Claude Code+description: "Step-by-step tutorial to add the openstatus MCP server to Claude Code so the agent can read and manage your status pages from the terminal"+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~3 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account, [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) installed |++In this tutorial, you'll connect the openstatus MCP server to Claude Code so the agent can list your status pages, draft incidents, and schedule maintenance windows directly from your terminal.++### Prerequisites++- An openstatus account ([openstatus.dev](https://www.openstatus.dev))+- Claude Code installed and signed in (`claude --version`)++### What you'll get++By the end of this tutorial, you'll have:+- An openstatus API key dedicated to Claude Code+- The openstatus MCP server registered as a Claude Code tool+- A working first prompt that lists your status pages++## 1. Create an API key++Open the openstatus dashboard, go to **Settings → API Tokens**, and click **Create Token**.++Pick a scope:++- **Read-only** — Claude Code can list status pages, reports, and maintenance windows but cannot create or modify anything. Best for exploration and on-call summaries.+- **Read & write** — Claude Code can also create status reports, append updates, resolve incidents, and schedule maintenance.++<Aside type="tip">Start with a read-only key while you get familiar with the tools. You can issue a write key later — scopes are immutable on a given key, so you'll create a new one rather than upgrading.</Aside>++Copy the key (it starts with `os_`). You'll only see it once.++## 2. Add the MCP server to Claude Code++Claude Code talks to the openstatus MCP server over Streamable HTTP. Register it with the `claude mcp add` command:++```bash+claude mcp add \+ --transport http \+ --scope user \+ --header "x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \+ openstatus \+ https://api.openstatus.dev/mcp+```++The flags:++- `--transport http` — the openstatus MCP server is a stateless HTTP endpoint, not a local stdio process.+- `--scope user` — registers the server for every Claude Code session on your machine. Use `--scope project` if you want to commit a project-local `.mcp.json` so your team picks it up automatically (omit the header from the committed file and rely on `${OPENSTATUS_API_KEY}` expansion).+- `--header "x-openstatus-key: …"` — the same API key the openstatus CLI, REST API, and Terraform provider use.++### Project-scoped alternative++If you'd rather commit the configuration to your repo, create a `.mcp.json` at the project root:++```json+{+ "mcpServers": {+ "openstatus": {+ "type": "http",+ "url": "https://api.openstatus.dev/mcp",+ "headers": {+ "x-openstatus-key": "${OPENSTATUS_API_KEY}"+ }+ }+ }+}+```++Then export `OPENSTATUS_API_KEY` in your shell. Claude Code expands the variable at connection time, so the key never lands in version control.++## 3. Verify the connection++Open Claude Code and run:++```+/mcp+```++You should see `openstatus` listed as **connected**, with the registered tools (`list_status_pages`, `list_page_components`, `list_status_reports`, `list_maintenances`, and — if your key has write scope — `create_status_report`, `add_status_report_update`, `update_status_report`, `resolve_status_report`, `create_maintenance`).++If the server shows as disconnected, see [Troubleshooting](#troubleshooting) below.++## 4. Try your first prompt++Ask Claude Code something that exercises a read tool:++```+> list my openstatus status pages+```++Claude Code will call `list_status_pages`, prompt you to approve the call, and return the page slugs and ids in your workspace.++If you have a write-scoped key, try drafting an incident — Claude Code will show you the title, status, message, and notify choice **before** firing the tool, so nothing reaches subscribers without an explicit approval:++```+> draft a status report on my "api" page: investigating elevated latency on the payment endpoint+```++<Aside>Every mutation tool requires an explicit `notify: true | false`. Claude Code will ask whether to notify subscribers — answer before approving the tool call.</Aside>++## What you've accomplished++- ✅ Created an openstatus API key scoped for Claude Code+- ✅ Registered the openstatus MCP server with `claude mcp add`+- ✅ Verified the connection with `/mcp`+- ✅ Ran your first read and (optionally) write tool calls++## Troubleshooting++### `/mcp` shows openstatus as disconnected++1. **Re-check the header:** run `claude mcp list` and confirm the `x-openstatus-key` value matches a key visible in **Settings → API Tokens**. Whitespace and trailing newlines are common copy-paste failures.+2. **Reachability:** `curl -i -H "x-openstatus-key: os_..." https://api.openstatus.dev/mcp` should return a `200` with a `mcp-session-id` header. A `401` means the key is wrong or revoked; a network error means a proxy or firewall is blocking the connection.+3. **Re-add the server:** `claude mcp remove openstatus` then re-run the `claude mcp add` command from step 2.++### "Tool not available" when asking Claude Code to create an incident++Your API key is read-only. Claude Code only sees the `list_*` tools — the server filters mutation tools out of `tools/list` for read-only keys. Issue a new key with **Read & write** scope and re-add the server.++### Audit log shows `actor_type = 'mcp'` for changes I made manually++That's expected — every mutation routed through Claude Code (or any other MCP client) is attributed to `mcp` in the audit log, with `actor_id` set to the API key id and `actor_user_id` set to the user who created the key. This is how openstatus separates AI-driven actions from CLI, dashboard, and API mutations.++## What's next?++- **[MCP Server Reference](/docs/reference/mcp-server)** — full tool schema, error codes, and the contract behind the required `notify` flag+- **[Connect to other MCP clients](/docs/reference/mcp-server#configure-claude-desktop)** — the same API key works for Claude Desktop, Cursor, and any other MCP-compatible client+- **[Get started with the openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli)** — for terminal workflows that don't need an LLM in the loopdiff --git a/apps/web/src/content/pages/docs/tutorial/how-to-create-monitor.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-create-monitor.mdxnew file mode 100644index 000000000..ad1249d1a--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-create-monitor.mdx@@ -0,0 +1,146 @@+---+category: Tutorials+title: Create an Uptime Monitor in 5 Minutes+description: "Set up your first uptime monitor with openstatus — track response time, status codes, and availability from 35+ global locations."+---++++## What you'll learn++In this tutorial, you'll learn how to create your first monitor an automated watchdog for your services. A monitor periodically checks your endpoints to ensure they are available, performant, and returning the correct data. Think of it as a `curl` command that runs 24/7, providing continuous insights into the health of your application.++### Prerequisites++- An openstatus account (free tier available at [openstatus.dev](https://www.openstatus.dev))+- A URL endpoint to monitor (can be your own service or any public URL)++### What you'll build++By the end of this tutorial, you'll have:+- A working uptime monitor checking your endpoint every minute+- Real-time metrics showing response time and status codes+- Understanding of how to customize HTTP requests for different scenarios+++## Get Started in 1 Minute++Let's get your first uptime check up and running.++### 1. Create the Monitor++ <Image+ src="/docs/tutorial/create-monitor/create-monitor-1.png"+ alt="Monitors page showing the Create Monitor button in the sidebar"+ />++Navigate to the **Monitors** page from the sidebar and click the **Create Monitor** button. This will open a new configuration screen.+++### 2. Configure the Basics++ <Image+ src="/docs/tutorial/create-monitor/create-monitor-2.png"+ alt="Monitor creation form with name and URL fields"+ />++To get your monitor started, you only need to provide two essential pieces of information:+- **Name:** A clear, descriptive name for your monitor (e.g., "Production API Health Check" or "Homepage Uptime").+- **URL:** The full URL of the endpoint you want to test (e.g., `https://openstat.us`).++As soon as you enter the URL, our monitoring tool will automatically begin tracking key performance metrics for every check, including:+- **Response Time:** The total time it takes for the request to complete.+- **Status Code:** The HTTP status code returned by the server (e.g., 200, 404, 500).+- **Response Headers:** A detailed view of the headers returned by the server.+- **Detailed Timing Metrics:** A breakdown of the time spent on each phase of the request (DNS lookup, TCP connection, TLS handshake, etc.)+++ <Image+ src="/docs/tutorial/create-monitor/monitor-overview.png"+ alt="Monitor overview dashboard showing response time and status code charts"+ />++**Checkpoint:** After saving, you should see your monitor's overview page with response time and status code charts. If data appears within a few seconds, your monitor is running.+++### 3. Customizing the HTTP Request++Your monitor doesn't just have to be a simple `GET` request. You can customize the HTTP request to simulate real-world traffic and test specific scenarios.++#### HTTP Method++Choose the appropriate HTTP method for your check. While `GET` is the default and most common for simple health checks, you can also select `POST`, `HEAD`, `OPTIONS`, `PUT`, `PATCH`, `DELETE`, or `TRACE`.++- `GET`: Retrieve data from an endpoint. The most common choice for health checks.+- `POST`: Send data to an endpoint, for example, to test a form submission or API creation endpoint.+- `HEAD`: Same as `GET`, but without the response body. Useful for quickly checking if a resource exists.+- `OPTIONS`: Retrieve the supported HTTP methods for a resource.+- `PUT`: Update an existing resource.+- `PATCH`: Partially update an existing resource.+- `DELETE`: Delete a resource.+- `TRACE`: Echo the request back to the client.++#### Request Body++If you select the `POST` method, you can add a Request Body to your monitor's configuration. This is essential for testing API endpoints that require a JSON, form-encoded, or other data payload. Simply enter the data you want to send in the provided text area.++#### Custom Headers++You can add any number of custom HTTP headers to your request. This is particularly useful for:++- **Authentication:** Sending an Authorization token (e.g., a Bearer token) to test a protected endpoint.+- **Content Type:** Setting a `content-type` header to specify a content type (e.g., `application/json`).+- **Content Negotiation:** Setting an Accept header to request a specific content type from the server (e.g., `application/json`).+- **Simulating Clients:** Adding a User-Agent header to simulate traffic from a specific browser or device.+++<Aside title="We've got your User-Agent covered!">++openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.++</Aside>+++## Important Considerations++### Monitoring Third-Party Endpoints++<Aside>++If you're monitoring a URL you don't own (like `google.com` or a partner API), your requests might be blocked by firewalls or rate limiters (e.g., Cloudflare). This is a security measure on their end to prevent scraping or denial-of-service attacks.++</Aside>++## What you've accomplished++Congratulations! You've successfully:+- ✅ Created your first uptime monitor+- ✅ Configured basic HTTP monitoring settings+- ✅ Learned about customizing requests with methods, headers, and body+- ✅ Understood key monitoring metrics (response time, status codes, timing breakdown)++## What's next?++Now that you have a monitor running, you can:++- **[Create a Status Page](/docs/tutorial/how-to-create-status-page)** - Share your service status publicly with users+++### Learn more++- **[Understanding Uptime Monitoring](/docs/concept/uptime-monitoring)** - Deep dive into monitoring concepts+- **[HTTP Monitor Reference](/docs/reference/http-monitor)** - Complete technical specifications++++## Video Tutorial++<ShowcaseYouTube+ entries={[+ {+ href: 'https://www.youtube.com/embed/nYti3DjHoWY?si=RBGFHzoHFmwphRf',+ title: 'Create your first monitor',+ },++ ]}+/>diff --git a/apps/web/src/content/pages/docs/tutorial/how-to-create-private-location.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-create-private-location.mdxnew file mode 100644index 000000000..4ad9e28a8--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-create-private-location.mdx@@ -0,0 +1,135 @@+---+category: Tutorials+title: Create a Private Location+description: "Set up monitoring from your own infrastructure using Docker-based private probes"+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~15 minutes |+| **Level** | Advanced |+| **Prerequisites** | openstatus account, Docker installed |++In this tutorial, you'll set up a **private location** — a monitoring probe running on your own infrastructure. This lets you monitor internal applications, private APIs, and network resources behind your firewall without exposing them to the public internet.++### Prerequisites++- An openstatus account ([openstatus.dev](https://www.openstatus.dev))+- Docker installed on your server or local machine (`docker --version` to verify)+- At least one monitor already created (see [Create Your First Monitor](/docs/tutorial/how-to-create-monitor))++### What you'll build++By the end of this tutorial, you'll have:+- A private location configured in openstatus+- A Docker container running the monitoring probe on your infrastructure+- Monitors assigned to check from your private location++<Aside type="caution">Private locations are currently in **beta**. Some features like incident creation and public status page support are not yet available for private locations.</Aside>++## What are private locations?++Private locations allow you to monitor internal applications from within your own infrastructure, rather than solely relying on our public cloud-based regions. By deploying monitoring probes as Docker containers on your own machines, you can:++- Monitor internal APIs and services behind your firewall+- Get detailed timing and latency data from your specific deployment location+- Monitor from on-prem servers, Raspberry Pi devices, or any Docker-capable machine++## Step 1: Create a private location++1. Navigate to **Settings** > **Private Locations** in your openstatus dashboard+2. Click **Create Private Location**+3. Give your location a descriptive name (e.g., "Office Network", "AWS us-east-1 VPC")+4. Save the configuration++After creation, you'll receive a **token**. Copy this token — you'll need it in the next step.++<Aside type="caution">Keep your token secure. It authenticates your probe with the openstatus platform.</Aside>++## Step 2: Deploy the Docker probe++Run the monitoring probe on your server using Docker:++```bash+docker run -d \+ --name openstatus-probe \+ --restart unless-stopped \+ -e OPENSTATUS_TOKEN=<your-token> \+ ghcr.io/openstatushq/probe:latest+```++Replace `<your-token>` with the token from Step 1.++### Verify the container is running++```bash+docker ps --filter name=openstatus-probe+```++You should see the container listed with a status of `Up`:++```+CONTAINER ID IMAGE STATUS NAMES+abc123 ghcr.io/openstatushq/probe:latest Up 2 minutes openstatus-probe+```++## Step 3: Assign monitors to your private location++1. Go to **Settings** > **Private Locations** and select your location+2. Choose which monitors should run from this private location+3. Alternatively, edit an individual monitor and select your private location in its settings++**Checkpoint:** Within a couple of minutes, you should see monitoring data appearing in your monitor's overview from your private location.++## What you've accomplished++You've successfully:+- ✅ Created a private location in openstatus+- ✅ Deployed a monitoring probe on your own infrastructure+- ✅ Assigned monitors to check from your private location++## Current limitations++- Incidents are **not yet created** for monitors running via private locations. Continue using openstatus public regions if you need alerting.+- Public monitors on status pages **do not yet support** private locations.++## Troubleshooting++### Container exits immediately++Check the container logs for errors:++```bash+docker logs openstatus-probe+```++Common causes:+- **Invalid token:** Double-check the token value — ensure no extra spaces or newlines+- **Network issues:** Ensure the container can reach `api.openstatus.dev` on port 443++### No data appearing in the dashboard++1. Verify the container is running: `docker ps --filter name=openstatus-probe`+2. Check that you've assigned at least one monitor to the private location+3. Wait 2-3 minutes — there may be a short delay before the first check runs++### Container can't reach internal services++If the probe needs to reach services on your host machine, use Docker's host networking:++```bash+docker run -d \+ --name openstatus-probe \+ --restart unless-stopped \+ --network host \+ -e OPENSTATUS_TOKEN=<your-token> \+ ghcr.io/openstatushq/probe:latest+```++## What's next?++- **[Read our Raspberry Pi deployment guide](https://www.openstatus.dev/blog/deploy-private-locations-raspberry-pi)** — Deploy probes on low-cost hardware+- **[Create a Monitor](/docs/tutorial/how-to-create-monitor)** — Set up more monitors to run from your private locationdiff --git a/apps/web/src/content/pages/docs/tutorial/how-to-create-status-page.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-create-status-page.mdxnew file mode 100644index 000000000..190b89824--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-create-status-page.mdx@@ -0,0 +1,98 @@+---+category: Tutorials+title: Create a Status Page+description: "A step-by-step tutorial to create and publish your first status page"+---+++++## What you'll learn++| | |+|---|---|+| **Time** | ~5 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account, at least one monitor |++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.++### Prerequisites++- An openstatus account+- At least one monitor created (see [Create Your First Monitor](/docs/tutorial/how-to-create-monitor))++### What you'll build++By the end of this tutorial, you'll have:+- A public status page showing your service health+- Monitors displayed on your status page+- Understanding of privacy and security options++## Get started++### 1. Create the status page++Navigate to the **Status Pages** page from the sidebar and click the **Create Status Page** button. This will open a new configuration screen.++<Image+ src="/docs/tutorial/create-status-page/create-status-page-1.png"+ alt="Status Pages sidebar with the Create Status Page button highlighted"+/>+++### 2. Configure the status page++Fill in the basic details for your status page:++- **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`)++<Image+ src="/docs/tutorial/create-status-page/create-status-page-2.png"+ alt="Status page configuration form showing title, slug, and monitor selection"+/>++#### Add monitors++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.++#### Custom domain++You can use your own domain (e.g., `status.yourdomain.com`) instead of the default `*.openstatus.dev` subdomain. To set this up:++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.++The dashboard will show you the exact DNS records to configure after you save your custom domain.++See the [Status Page Reference](/docs/reference/status-page) for detailed DNS configuration instructions.++#### Password protection++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.++**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.++## What you've accomplished++Great work! You've successfully:+- ✅ Created your first status page+- ✅ Added monitors to display service health+- ✅ Learned about custom domains and password protection++## What's next?++Now that you have a basic status page, you can:++- **[Configure Your Status Page](/docs/tutorial/how-to-configure-status-page)** - Customize appearance and add more features+- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** - Learn how to communicate effectively++### Learn more++- **[Status Page Reference](/docs/reference/status-page)** - Complete configuration options+- **[Understanding Uptime Values](/docs/concept/uptime-calculation-and-values)** - How uptime is calculateddiff --git a/apps/web/src/content/pages/docs/tutorial/how-to-import-status-page.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-import-status-page.mdxnew file mode 100644index 000000000..366214718--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-import-status-page.mdx@@ -0,0 +1,153 @@+---+category: Tutorials+title: Import a Status Page from Another Provider+description: "Import your existing status page setup from Atlassian Statuspage, Better Stack, or Instatus into openstatus"+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~2 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account |++Migrating away from your current status page provider does not have to mean starting from scratch. openstatus can import your existing status page configuration -- including components, incidents, maintenances, and subscribers -- directly from another provider. This tutorial walks through the provider-agnostic import flow step by step.++## Supported providers++openstatus currently supports importing from three providers:++- **[Atlassian Statuspage](https://openstatus.dev/guides/migrate-from-atlassian-statuspage)** -- The most widely used hosted status page solution.+- **[Better Stack](https://openstatus.dev/guides/migrate-from-betterstack)** -- Monitoring and status page platform (formerly Better Uptime).+- **[Instatus](https://openstatus.dev/guides/migrate-from-instatus)** -- A modern status page service with component-level tracking.++Each link above points to a provider-specific migration guide with detailed instructions on API key generation and data mapping.++## Step-by-step import++### 1. Get your API key++You need a read-access API key from your current provider. The key is used only during the import and is not stored after the process completes.++<Aside>+Where to find your API key varies by provider. See the provider-specific guides linked above for exact instructions:+- **Statuspage:** Organization-level API key in your Atlassian account settings.+- **Better Stack:** API token from the Better Stack dashboard under Integrations.+- **Instatus:** API key from your Instatus workspace settings.+</Aside>++### 2. Open the import page++In the openstatus dashboard, navigate to **Status Pages** and select the status page you want to import into. If you have not yet created a status page, create one first -- see [Create a Status Page](/docs/tutorial/how-to-create-status-page) for instructions.++Open the **Components** tab and scroll down to the **Import** section at the bottom of the page.++### 3. Select your provider and enter credentials++Choose your source provider from the dropdown and paste your API key. Depending on the provider, you may also need to supply additional identifiers (for example, a Page ID for Atlassian Statuspage).+++### 4. Preview the import++After submitting your credentials, the importer fetches your existing data and displays a preview summary. No data is written at this stage -- the preview is read-only.++The preview includes:++- **Resource counts** -- Number of components, component groups, incidents, maintenances, and subscribers that will be imported.+- **Warnings** -- Any resources that cannot be imported or require manual attention (for example, unsupported subscriber types or resources that exceed your plan limits).+- **Mapping details** -- How source resources map to openstatus equivalents.++Review the summary carefully before proceeding. If the counts do not match what you expect, verify that your API key has sufficient permissions to read all resources.+++### 5. Configure import options++Use the toggles to enable or disable import of each resource type. For example, you may want to import only components and skip historical incidents. Available toggles depend on what the selected provider supports.++<Aside type="caution">+Importing incidents and maintenances creates historical records in openstatus. These are imported as-is and cannot be bulk-deleted after import.+</Aside>++### 6. Run the import++Click **Import** to start the process. The import runs in phases:++1. **Components and groups** -- Structural elements are created first so that incidents and maintenances can reference them.+2. **Incidents** -- Historical and active incidents, including updates and component impact.+3. **Maintenances** -- Scheduled and completed maintenance windows.+4. **Subscribers** -- Email subscribers (where supported by the source provider).+5. **Monitors** -- Existing monitoring checks (Better Stack only).++A progress indicator shows the current phase and any errors encountered. When the import finishes, you are redirected to your status page configuration with all imported data in place.+++## What gets imported++Not every provider exposes the same data. The table below summarizes what openstatus imports from each source:++| Resource | Statuspage | Better Stack | Instatus |+|---|---|---|---|+| Status page | Yes | Yes | Yes |+| Components and groups | Yes | Yes | Yes |+| Incidents | Yes | Yes | Yes |+| Maintenances | Yes | Yes | Yes |+| Subscribers | Yes (email only) | No | Yes (email only) |+| Monitors | No | Yes | No |++<Aside type="tip">+For a detailed breakdown of how each resource type is mapped, see the provider-specific migration guides:+[Atlassian Statuspage](https://openstatus.dev/guides/migrate-from-atlassian-statuspage),+[Better Stack](https://openstatus.dev/guides/migrate-from-betterstack),+[Instatus](https://openstatus.dev/guides/migrate-from-instatus).+</Aside>++## After import++The import creates resources in openstatus but does not automatically make your status page live or redirect traffic. Complete the following steps to finalize your migration:++1. **Verify imported data.** Open your status page and confirm that components, incidents, and maintenances appear correctly. Check that component groups are structured as expected.++2. **Connect monitors to static components.** Imported components may not have monitors attached. Navigate to each component and link an existing openstatus monitor, or [create a new monitor](/docs/tutorial/how-to-create-monitor) for it.++3. **Update DNS for your custom domain.** If you are migrating a custom domain (e.g., `status.yourdomain.com`), update your CNAME record to point to `status.openstatus.dev`. See the [Status Page Reference](/docs/reference/status-page) for DNS configuration details.++4. **Invite subscribers.** If your provider does not support subscriber export (Better Stack) or you need to re-verify email subscribers, use the openstatus subscription system to notify your users of the new page.++## Troubleshooting++### Invalid API key++The import fails immediately with an authentication error. Double-check that you copied the full key and that it has read permissions. Some providers require organization-level keys rather than personal tokens. Regenerate the key if necessary.++### Plan limits exceeded++openstatus plans have caps on the number of components and monitors. If your import would exceed these limits, the preview step displays a warning before any data is written. You can either upgrade your plan or disable import of certain resource types to stay within limits.++### Partial import++If the import succeeds for some phases but fails for others (for example, components import successfully but incidents fail due to a rate limit or timeout), the successfully imported resources remain in place. Fix the underlying issue and re-run the import. Only the failed phases will be retried; already-imported resources are not duplicated.++<Aside type="caution">+If a partial import leaves your status page in an inconsistent state, you can delete the imported resources manually and start the import again from scratch.+</Aside>++### Duplicate incidents on re-import++Running the import a second time does not deduplicate incidents or maintenances. If you need to re-import, delete the previously imported records first to avoid duplicate entries appearing on your status page.++## What's next?++Now that your data is in openstatus, explore these resources to get the most out of your new setup:++- **[Configure Your Status Page](/docs/tutorial/how-to-configure-status-page)** -- Customize the appearance, add a logo, and configure notification preferences.+- **[Create Your First Monitor](/docs/tutorial/how-to-create-monitor)** -- Set up synthetic monitoring for your imported components.+- **[Status Page Reference](/docs/reference/status-page)** -- Full reference for all status page configuration options.+- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** -- Best practices for transparent incident communication.++### Provider-specific guides++- [Migrate from Atlassian Statuspage](https://openstatus.dev/guides/migrate-from-atlassian-statuspage)+- [Migrate from Better Stack](https://openstatus.dev/guides/migrate-from-betterstack)+- [Migrate from Instatus](https://openstatus.dev/guides/migrate-from-instatus)diff --git a/apps/web/src/content/pages/docs/tutorial/how-to-manage-openstatus-with-terraform-cli.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-manage-openstatus-with-terraform-cli.mdxnew file mode 100644index 000000000..96f7ed1c9--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-manage-openstatus-with-terraform-cli.mdx@@ -0,0 +1,411 @@+---+category: Tutorials+title: Manage Your openstatus Stack with Terraform and the CLI+description: "Use Terraform to manage monitors, status pages, and notifications as code — and the openstatus CLI to handle incident status reports."+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~20 minutes |+| **Level** | Intermediate |+| **Prerequisites** | openstatus account, Terraform installed, CLI installed |++In this tutorial, you'll set up a complete monitoring stack using two tools:++- **Terraform** to manage your infrastructure — monitors, status pages, notifications. These are long-lived resources that change infrequently and benefit from code review, version control, and `terraform plan`.+- **The openstatus CLI** to handle operational tasks — creating and updating status reports during incidents. These are time-sensitive actions that need to happen fast, often from a terminal or a CI script.++### Prerequisites++- An openstatus account ([sign up free](https://www.openstatus.dev))+- [Terraform](https://developer.hashicorp.com/terraform/install) installed+- The openstatus CLI installed ([installation guide](/docs/tutorial/get-started-with-openstatus-cli))+- Your API token from workspace settings (Settings > API)++### What you'll build++By the end of this tutorial, you'll have:+- HTTP, TCP, and DNS monitors deployed via Terraform+- A public status page with grouped components+- Slack notifications wired to your monitors+- A status report workflow using the CLI for incident communication++## Part 1 — Infrastructure with Terraform++### Step 1 — Set up the provider++Create a new directory for your Terraform configuration and add a `main.tf` file:++```terraform+terraform {+ required_providers {+ openstatus = {+ source = "openstatusHQ/openstatus"+ version = "~> 0.1"+ }+ }+}++provider "openstatus" {+ api_token = var.openstatus_api_token+}++variable "openstatus_api_token" {+ type = string+ sensitive = true+}+```++Initialize the provider:++```bash+terraform init+```++<Aside>Set the token via an environment variable to avoid passing it on every run: `export TF_VAR_openstatus_api_token="your-token"`</Aside>++### Step 2 — Define your monitors++Add monitors to your `main.tf`. We'll create three types — HTTP, TCP, and DNS.++**HTTP monitor with assertions:**++```terraform+resource "openstatus_http_monitor" "api" {+ name = "API Health Check"+ description = "Monitors the main API health endpoint."+ url = "https://api.example.com/health"+ periodicity = "5m"+ method = "GET"+ timeout = 30000+ active = true+ public = true+ regions = ["fly-iad", "fly-ams", "fly-syd"]++ headers {+ key = "Accept"+ value = "application/json"+ }++ status_code_assertions {+ target = 200+ comparator = "eq"+ }++ body_assertions {+ target = "ok"+ comparator = "contains"+ }+}+```++**TCP monitor for database connectivity:**++```terraform+resource "openstatus_tcp_monitor" "database" {+ name = "PostgreSQL"+ description = "Checks that the database port is reachable."+ uri = "db.example.com:5432"+ periodicity = "1m"+ timeout = 10000+ active = true+ regions = ["fly-iad", "fly-fra"]+}+```++**DNS monitor with record assertion:**++```terraform+resource "openstatus_dns_monitor" "domain" {+ name = "DNS Resolution"+ description = "Validates the A record for example.com."+ uri = "example.com"+ periodicity = "10m"+ active = true+ regions = ["fly-iad", "fly-ams"]++ record_assertions {+ record = "A"+ comparator = "eq"+ target = "93.184.216.34"+ }+}+```++### Step 3 — Add notifications++Wire up a Slack notification so you get alerted when monitors fail:++```terraform+variable "slack_webhook_url" {+ type = string+ sensitive = true+}++resource "openstatus_notification" "slack" {+ name = "Slack Alerts"+ provider_type = "slack"+ monitor_ids = [+ openstatus_http_monitor.api.id,+ openstatus_tcp_monitor.database.id,+ ]++ slack {+ webhook_url = var.slack_webhook_url+ }+}+```++<Aside>The provider supports 12 notification types including PagerDuty, Discord, Email, OpsGenie, and webhooks. See the [Terraform provider reference](/docs/reference/terraform#openstatus_notification) for all options.</Aside>++### Step 4 — Create a status page with components++Define a public status page and organize monitors into component groups:++```terraform+resource "openstatus_status_page" "main" {+ title = "Example Inc. Status"+ slug = "example-status"+ description = "Real-time status for all Example Inc. services."+ homepage_url = "https://example.com"+ contact_url = "https://example.com/support"+}++resource "openstatus_status_page_component_group" "services" {+ page_id = openstatus_status_page.main.id+ name = "Services"+}++resource "openstatus_status_page_component_group" "infrastructure" {+ page_id = openstatus_status_page.main.id+ name = "Infrastructure"+}++resource "openstatus_status_page_component" "api_component" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_http_monitor.api.id+ name = "API"+ group_id = openstatus_status_page_component_group.services.id+ order = 1+ group_order = 1+}++resource "openstatus_status_page_component" "db_component" {+ page_id = openstatus_status_page.main.id+ type = "monitor"+ monitor_id = openstatus_tcp_monitor.database.id+ name = "Database"+ group_id = openstatus_status_page_component_group.infrastructure.id+ order = 2+ group_order = 1+}+```++### Step 5 — Plan and apply++Preview the changes Terraform will make:++```bash+terraform plan+```++You should see all resources listed as "will be created". Apply them:++```bash+terraform apply+```++**Checkpoint:** After applying, verify everything is live:+- Open your openstatus dashboard — your monitors should appear in the Monitors tab+- Visit your status page at `https://<your-slug>.openstatus.dev` — you should see your component groups and monitors++### Step 6 — Update your infrastructure++To make changes, edit your `.tf` files and re-apply. For example, add a new region to the API monitor:++```terraform+ regions = ["fly-iad", "fly-ams", "fly-syd", "fly-nrt", "fly-gru"]+```++Then:++```bash+terraform plan # Review the diff+terraform apply # Apply the update+```++Terraform only modifies what changed — the monitor gets updated in place, no downtime.++### Step 7 — Import existing resources++If you already have monitors, status pages, or notifications created in the dashboard, you can generate the corresponding Terraform configuration automatically using the CLI:++```bash+openstatus terraform generate+```++This exports all your workspace resources — monitors, status pages, notifications, and maintenance windows — into `.tf` files ready to use. It's the fastest way to adopt infrastructure as code for an existing setup.++Once the files are generated, import the resources into Terraform state so it knows they already exist:++```bash+terraform import openstatus_http_monitor.api <monitor-id>+terraform import openstatus_status_page.main <page-id>+terraform import openstatus_notification.slack <notification-id>+```++After importing, run `terraform plan` to ensure your `.tf` files match the imported state. Adjust any drift until the plan shows no changes.++## Part 2 — Status reports with the CLI++Terraform is great for infrastructure, but status reports are operational — you create them when an incident is happening and update them as you investigate and resolve. The CLI is the right tool here.++### Step 8 — Configure the CLI++Make sure your API token is set:++```bash+export OPENSTATUS_API_TOKEN="your-api-token"+```++Verify your setup:++```bash+openstatus whoami+```++### Step 9 — Create a status report++When an incident starts, create a status report and link it to your status page and affected components:++```bash+openstatus status-report create \+ --title "API Elevated Latency" \+ --status investigating \+ --message "We are investigating increased response times on the API." \+ --page-id <page-id> \+ --component-ids <api-component-id> \+ --notify+```++Key flags:+- **`--status`**: The initial incident state — `investigating`, `identified`, `monitoring`, or `resolved`.+- **`--page-id`**: Links the report to your status page so visitors can see it.+- **`--component-ids`**: Marks specific components as affected (comma-separated for multiple).+- **`--notify`**: Sends a notification to all status page subscribers.++<Aside>Find your page and component IDs with `openstatus status-page list` and `openstatus status-page info <page-id>`.</Aside>++### Step 10 — Post updates as you investigate++As the incident progresses, add updates to the report. Each update changes the status and adds a timestamped message:++```bash+# Root cause identified+openstatus status-report add-update <report-id> \+ --status identified \+ --message "Root cause identified: a misconfigured cache TTL is causing stale responses." \+ --notify++# Fix deployed, monitoring+openstatus status-report add-update <report-id> \+ --status monitoring \+ --message "Fix deployed to production. Monitoring response times for recovery."++# Incident resolved+openstatus status-report add-update <report-id> \+ --status resolved \+ --message "Response times have returned to normal. Incident resolved." \+ --notify+```++Each update appears on your public status page as a timeline entry, giving your users clear visibility into what happened and when.++### Step 11 — Review and manage reports++List recent incidents:++```bash+# All reports+openstatus status-report list++# Only active incidents+openstatus status-report list --status investigating++# Detailed view of a specific report+openstatus status-report info <report-id>+```++Update report metadata (title, affected components):++```bash+openstatus status-report update <report-id> \+ --title "API Elevated Latency — Cache Misconfiguration" \+ --component-ids <api-component-id>,<db-component-id>+```++Delete a report (e.g., created by mistake):++```bash+openstatus status-report delete <report-id>+```++## Putting it all together++Here's how the two tools fit into your workflow:++| Task | Tool | Why |+| :--- | :--- | :--- |+| Create/update monitors | Terraform | Version controlled, peer reviewed, reproducible |+| Create/update status pages | Terraform | Long-lived infrastructure, managed as code |+| Configure notifications | Terraform | Declarative, easy to audit |+| Report an incident | CLI | Fast, imperative, time-sensitive |+| Post incident updates | CLI | Happens in real-time during an outage |+| Trigger a monitor check | CLI | On-demand operational task |++## CLI commands cheat sheet++| Command | Description |+| :--- | :--- |+| `openstatus whoami` | Verify your API token and workspace |+| `openstatus status-report create` | Create a new incident report |+| `openstatus status-report add-update <id>` | Add a status update to an incident |+| `openstatus status-report update <id>` | Update report metadata (title, components) |+| `openstatus status-report list` | List all status reports |+| `openstatus status-report list --status investigating` | Filter by incident status |+| `openstatus status-report info <id>` | View a report's full timeline |+| `openstatus status-report delete <id>` | Delete a status report |+| `openstatus monitors list` | List all monitors |+| `openstatus monitors info <id>` | View monitor details and metrics |+| `openstatus monitors trigger <id>` | Trigger an immediate check |+| `openstatus status-page list` | List all status pages |+| `openstatus status-page info <id>` | View status page details and component IDs |+| `openstatus terraform generate` | Export workspace resources to Terraform `.tf` files |++## What you've accomplished++You've successfully:+- ✅ Deployed HTTP, TCP, and DNS monitors with Terraform+- ✅ Created a status page with component groups and monitor-linked components+- ✅ Configured Slack notifications for monitor failures+- ✅ Used the CLI to manage the full lifecycle of an incident status report+- ✅ Learned when to use Terraform vs. the CLI for different tasks++## What's next?++- **[Terraform Provider Reference](/docs/reference/terraform)** — Full specification for all resources and data sources+- **[Run Synthetic Tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — Automate monitoring in your CI/CD pipeline+- **[Export Metrics to an OTLP Endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — Send monitor data to your observability stack++## Learn more++- **[Understanding Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** — Why manage monitors as code+- **[CLI Reference](/docs/reference/cli-reference)** — Complete command documentation+- **[Status Report Reference](/docs/reference/status-report)** — Status report properties and lifecycle+- **[HTTP Monitor Reference](/docs/reference/http-monitor)** — Full HTTP monitor specification+- **[TCP Monitor Reference](/docs/reference/tcp-monitor)** — Full TCP monitor specification+- **[DNS Monitor Reference](/docs/reference/dns-monitor)** — Full DNS monitor specificationdiff --git a/apps/web/src/content/pages/docs/tutorial/how-to-setup-slack-agent.mdx b/apps/web/src/content/pages/docs/tutorial/how-to-setup-slack-agent.mdxnew file mode 100644index 000000000..b60f1bec0--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/how-to-setup-slack-agent.mdx@@ -0,0 +1,122 @@+---+category: Tutorials+title: Set Up the openstatus Slack Agent+description: "A step-by-step tutorial to install the openstatus Slack agent and manage incidents directly from Slack"+---+++## What you'll learn++| | |+|---|---|+| **Time** | ~5 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account, Slack workspace admin access |++In this tutorial, you'll learn how to install the openstatus Slack agent so you can manage incidents directly from your Slack workspace — no need to switch to the dashboard.++### Prerequisites++- An openstatus account ([openstatus.dev](https://www.openstatus.dev))+- A Slack workspace where you have permission to install apps++### What you'll get++By the end of this tutorial, you'll have:+- The openstatus Slack agent installed in your workspace+- The ability to create, update, and resolve incidents from Slack++## Install the Slack Agent++### 1. Go to Settings++Navigate to **Settings** > **Integrations** in your openstatus dashboard.++### 2. Install the Slack Integration++Click the **Install Slack** button. You'll be redirected to Slack's authorization page where you can select the workspace and channel you want to connect.++Grant the requested permissions and click **Allow** to complete the installation.++<Aside>Make sure you select the correct Slack workspace if you belong to multiple workspaces.</Aside>++### 3. Verify the Installation++After completing the OAuth flow, go to the Slack channel you selected and type:++```+@openstatus what's the status of my monitors?+```++The bot should respond with a summary of your monitors. If you see a response, the installation is working.++<Aside type="tip">The bot only responds when mentioned with `@openstatus` — it won't interrupt your conversations.</Aside>++### 4. Start Managing Incidents from Slack++Here are some examples of what you can do:++#### Create an incident++Notify your subscribers about a new issue.++```+@openstatus create an incident for the payment API – high latency detected.+```++#### Update an incident++Keep your status page updated while you investigate.++```+@openstatus keep the status page updated that we are still monitoring the issue.+```++#### Resolve an incident++Close an active incident and let your subscribers know.++```+@openstatus resolve the ongoing incident on my API status page.+```++#### Schedule maintenance++Plan downtime so subscribers are informed in advance.++```+@openstatus schedule a maintenance window for my database next Friday from 2–3 PM.+```++## What you've accomplished++Congratulations! You've successfully:+- ✅ Installed the openstatus Slack agent in your workspace+- ✅ Connected your openstatus account to Slack+- ✅ Learned how to manage incidents directly from Slack++## Troubleshooting++### The bot doesn't respond when mentioned++1. **Check the channel:** Make sure you're mentioning `@openstatus` in the channel you selected during installation.+2. **Check permissions:** Go to **Settings** > **Integrations** and verify the Slack integration shows as connected.+3. **Reinstall:** If the integration appears disconnected, click **Install Slack** again to re-authorize.++### "Not authorized" or permission errors++Your Slack workspace admin may need to approve the app. Ask your workspace admin to go to **Slack Admin** > **Manage Apps** and approve the openstatus integration.++### Bot responds but can't find monitors++Make sure you have at least one monitor and one status page created in your openstatus workspace before using incident commands.++### AI responses may be inaccurate++The openstatus Slack agent uses AI to interpret your messages and take actions on your behalf. Responses and actions may occasionally be incorrect, incomplete, or unexpected. Always review the bot's output — especially before publishing incident updates, resolving incidents, or scheduling maintenance — and confirm the change in your openstatus dashboard.+++## What's next?++- **[Create a Status Page](/docs/tutorial/how-to-create-status-page)** — share your service status publicly with users+- **[Create a Monitor](/docs/tutorial/how-to-create-monitor)** — set up uptime monitoring for your endpointsdiff --git a/apps/web/src/content/pages/guides/http-headers.mdx b/apps/web/src/content/pages/guides/http-headers.mdxindex 00e2e2c64..f1ed1d511 100644--- a/apps/web/src/content/pages/guides/http-headers.mdx+++ b/apps/web/src/content/pages/guides/http-headers.mdx@@ -23,8 +23,6 @@ Header-Name: header-valueHeader names are case-insensitive; values are not.-----## Request Headers**`Accept`**@@ -81,8 +79,6 @@ Identifies the client—browser, SDK, or monitoring tool.User-Agent: OpenStatus-Monitor/1.0```-----## Response Headers**`Cache-Control`**@@ -116,8 +112,6 @@ Instructs the client to store a cookie with given attributes.Set-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Strict```-----## Security Headers**`Content-Security-Policy`**@@ -144,8 +138,6 @@ Protects against clickjacking by controlling iframe embedding.X-Frame-Options: DENY```-----## Proxy and Infrastructure HeadersSet by reverse proxies, load balancers, and CDNs—not your origin server.@@ -161,8 +153,6 @@ Set by reverse proxies, load balancers, and CDNs—not your origin server.| `X-RateLimit-Remaining` | Requests remaining in the current window || `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |-----## Cloud Provider HeadersEach provider injects its own headers. Recognizing them tells you which layer handled the request—and where to look when something fails.@@ -194,8 +184,6 @@ Each provider injects its own headers. Recognizing them tells you which layer haBoth proxy requests through standard infrastructure. Expect `X-Forwarded-*` headers; request IDs may appear as `X-Request-Id` or `X-Correlation-Id` depending on your app framework.-----## Why This Matters for MonitoringResponse headers reveal more than status codes alone:diff --git a/apps/web/src/content/pages/guides/public-vs-private-status-pages.mdx b/apps/web/src/content/pages/guides/public-vs-private-status-pages.mdxindex f528a6f5a..e7d80eefe 100644--- a/apps/web/src/content/pages/guides/public-vs-private-status-pages.mdx+++ b/apps/web/src/content/pages/guides/public-vs-private-status-pages.mdx@@ -79,8 +79,6 @@ The right authentication depends on your audience. **Email domain protection** wChoose wrong and you'll either lock out legitimate users (too restrictive) or expose sensitive operational data to the wrong audience (too open).-----## You Probably Need BothTeams with more than 10 people typically aren't choosing between public and private - they're choosing what goes where. The public page gets curated, reviewed updates. The private page gets raw metrics, auto-incidents, and detailed context.diff --git a/apps/web/src/content/pages/guides/sla-vs-slo-vs-sli.mdx b/apps/web/src/content/pages/guides/sla-vs-slo-vs-sli.mdxindex afc374763..aaeb895e6 100644--- a/apps/web/src/content/pages/guides/sla-vs-slo-vs-sli.mdx+++ b/apps/web/src/content/pages/guides/sla-vs-slo-vs-sli.mdx@@ -23,8 +23,6 @@ Getting this wrong has real consequences. Either you over-promise to customers aHere's what they actually mean, how they relate, and how to use them without screwing up.-----## What They Actually Are### SLI (Service Level Indicator)@@ -58,8 +56,6 @@ An SLA is your public promise to customers, with real consequences if you fail.This is a legal commitment. It has teeth. Miss it and you're writing refund checks or issuing service credits. That's the point—it's supposed to cost you when you fail customers.-----## The HierarchyThese aren't interchangeable terms. They stack:@@ -79,8 +75,6 @@ The gap between your SLO (99.95%) and your SLA (99.9%) is your **error budget**.If your SLO and SLA are the same number, one bad deploy breaks your promises. You've eliminated the margin that makes continuous deployment possible.-----## Common Mistakes Teams Make### 1. SLA Without SLOs@@ -113,8 +107,6 @@ Your documented SLI is "the site should feel fast." How do you measure feelings?**The fix:** Define specific, measurable thresholds. "P95 page load time under 2 seconds" is measurable. "Feels fast" is not.-----## Real-World Examples### Stripe (Doing It Right)@@ -135,8 +127,6 @@ They marketed an aggressive SLA to win enterprise deals but never built the infrThe lesson: don't promise what you can't measure. And don't measure without setting realistic internal targets first.-----## How Status Pages Fit In### Public Status Page (Display SLAs)@@ -157,8 +147,6 @@ Whether public or private, everything flows from the SLIs. If you can't measureYour entire reliability strategy—internal targets, customer promises, incident response priorities—depends on accurate, continuous SLI measurement.-----## "But We're Just Three People"If you're a small startup with 5 engineers and 200 customers, implementing a full SLI/SLO/SLA framework might feel like bringing a spreadsheet to a knife fight. You're not wrong.@@ -179,8 +167,6 @@ You'll know when you need the full framework: when enterprise customers start asUntil then? Keep it simple. Measure. Communicate. Don't over-promise.-----## The Bottom LineYou can't have reliable SLAs without disciplined SLOs. You can't have meaningful SLOs without accurate SLIs.diff --git a/apps/web/src/content/pages/guides/what-is-a-status-page.mdx b/apps/web/src/content/pages/guides/what-is-a-status-page.mdxindex 690868d92..f684a73c4 100644--- a/apps/web/src/content/pages/guides/what-is-a-status-page.mdx+++ b/apps/web/src/content/pages/guides/what-is-a-status-page.mdx@@ -27,8 +27,6 @@ When something breaks in production, users need to know if the problem is on youThat single source of truth is the status page. It exists to deflect support load during outages, build trust through honest communication, and signal to enterprise buyers that you take reliability seriously.-----## What a Status Page Actually ShowsA useful status page has four things:@@ -53,8 +51,6 @@ Planned downtime, announced in advance with a window, affected components, and eA rolling view of the last 30, 60, or 90 days showing uptime percentages and past incidents. This is your reliability proof. Enterprise buyers will scroll through it before signing a contract.-----## Why Companies Use Status Pages### Deflect Support Load@@ -73,8 +69,6 @@ Enterprise buyers often require a public status page before signing. It's tableA status page is also a forcing function for incident response. The act of writing a public update clarifies what you actually know, what you're doing, and what's still uncertain. It's a discipline as much as a communication channel.-----## Public vs Private Status Pages**Public** pages are for customers. They're curated, lag slightly behind real-time, and focus on user-impacting events. The audience is non-technical. Updates are written in plain language.@@ -83,8 +77,6 @@ A status page is also a forcing function for incident response. The act of writiMost mature SaaS companies run both. Public for trust, private for operations. See our guide on [public vs private status pages](/guides/public-vs-private-status-pages) for the deeper tradeoffs.-----## What Makes a Good Status Page### Hosted Independently@@ -103,8 +95,6 @@ Users should be able to subscribe to updates via email, SMS, Slack, RSS, or webhPast incidents stay accessible. Postmortems get linked from incident pages. Uptime metrics are computable and visible. This is how the status page doubles as a long-term reliability signal.-----## Common Mistakes**Only updating once an incident is resolved.** Users want updates *during* the incident. Resolved-after-the-fact is documentation, not communication.@@ -115,8 +105,6 @@ Past incidents stay accessible. Postmortems get linked from incident pages. Upti**No subscription options.** Forcing users to refresh manually means they don't get updates. They get frustrated and tweet at you instead.-----## How Status Pages Connect to MonitoringA status page is a communication layer. The data behind it comes from your [uptime monitoring](/guides/what-is-uptime-monitoring) and [synthetic monitoring](/guides/what-is-synthetic-monitoring) systems.@@ -129,8 +117,6 @@ The pipeline:Some teams automate step 3 for low-severity events. Most keep a human in the loop for anything customer-visible - automated status updates that fire on flaky monitors create more noise than they prevent.-----## The Bottom LineA status page is the simplest, highest-leverage trust-building tool you have during incidents. It deflects support load, signals maturity, and forces you to communicate clearly when things break.diff --git a/apps/web/src/content/pages/guides/what-is-incident-management.mdx b/apps/web/src/content/pages/guides/what-is-incident-management.mdxindex 5a3b7817f..5e2146cfe 100644--- a/apps/web/src/content/pages/guides/what-is-incident-management.mdx+++ b/apps/web/src/content/pages/guides/what-is-incident-management.mdx@@ -29,8 +29,6 @@ Every team deals with unplanned service disruptions. The difference between teamThat process is incident management. It runs three workstreams in parallel during every incident: fixing the technical problem, communicating with affected users, and learning from what happened so the same thing doesn't recur. Teams that neglect any of the three pay for it later.-----## The Incident LifecycleA well-run incident moves through six stages:@@ -69,8 +67,6 @@ Within a week, write up what happened. Timeline, root cause, customer impact, coThe point is to learn. If your postmortems aren't producing action items that actually get done, you're doing them wrong.-----## Roles During an IncidentSmall teams may have one person filling multiple roles. Larger teams split them explicitly.@@ -95,8 +91,6 @@ Engineers who actually fix the problem. They report to the IC. They focus on tecCaptures the timeline as the incident unfolds. Hugely valuable for the postmortem because human memory is unreliable two hours later. Often the IC takes notes themselves on smaller incidents.-----## Severity LevelsA working severity model:@@ -114,8 +108,6 @@ A common pitfall: severity inflation. If everything is SEV1, nothing is. Be honeSee our [incident severity matrix](/guides/incident-severity-matrix) for a more detailed framework.-----## Communication During an IncidentThe cadence:@@ -127,8 +119,6 @@ The cadence:Silence is the enemy. "Still investigating, next update at 14:30" is more useful than nothing. Users tolerate problems they're being told about; they don't tolerate problems they're being ignored about.-----## PostmortemsA good postmortem has:@@ -143,8 +133,6 @@ A good postmortem has:**Blameless framing.** People don't show up wanting to cause incidents. If a system allowed a human mistake to cause customer impact, the system is the actual problem. Postmortems that blame individuals produce defensive responses and dishonest writeups. Postmortems that focus on systems produce real improvements.-----## Common Mistakes**No formal declaration.** Engineers debug for an hour before someone says "wait, should we call this an incident?" By then, customers have been on Twitter for 45 minutes.@@ -159,8 +147,6 @@ A good postmortem has:**Communication as an afterthought.** Engineers focus on the fix and forget to update the status page for 90 minutes. Customers fill the void with assumptions, all of them worse than reality.-----## How Monitoring Fits InIncident management starts the moment you detect a problem. Detection comes from monitoring - external [uptime](/guides/what-is-uptime-monitoring) and [synthetic](/guides/what-is-synthetic-monitoring) checks for service availability, internal metrics for performance and errors.@@ -171,8 +157,6 @@ Then communication happens through your [status page](/guides/what-is-a-status-pThe pipeline: monitor → detect → declare → respond → communicate → resolve → learn. Every part has to work.-----## The Bottom LineIncident management isn't about preventing incidents - they happen to everyone. It's about handling them well when they do. Fast detection, organized response, honest communication, blameless learning.diff --git a/apps/web/src/content/pages/guides/what-is-mttr.mdx b/apps/web/src/content/pages/guides/what-is-mttr.mdxindex 8d848e00f..61a6b5b26 100644--- a/apps/web/src/content/pages/guides/what-is-mttr.mdx+++ b/apps/web/src/content/pages/guides/what-is-mttr.mdx@@ -31,8 +31,6 @@ There are four different "MTT-" acronyms in incident management. They all soundMTTR is the headline one - the average time from incident detection to service restored. It's the standard benchmark for how good a team is at handling outages. Here's what it actually measures, how it relates to the other three MTT-metrics, and how to actually move the number.-----## The Four MTT-MetricsMost incident timelines have four phases. Each has its own metric.@@ -77,8 +75,6 @@ Driven by: overall reliability, change management, system design.Less commonly tracked. Requires a long incident history to be meaningful. Often used for hardware originally; less precise for software systems.-----## How to Calculate MTTRThe basic math:@@ -96,8 +92,6 @@ The catch is defining "downtime." Two definitions in common use:Pick one. Be explicit about which. Don't switch between them.-----## The Average Is MisleadingThe mean is a bad summary statistic for incident duration because the distribution is heavy-tailed.@@ -118,8 +112,6 @@ The averages are nearly identical. Team B's customers are having a much worse exA team with MTTR of 30 minutes and P95 of 35 minutes is consistent. A team with MTTR of 30 minutes and P95 of 4 hours is occasionally catastrophic. Same average. Very different reality.-----## What's a Good MTTR?It depends on severity. A 4-hour MTTR is fine for SEV3. It's a crisis for SEV1.@@ -134,8 +126,6 @@ Rough benchmarks for SaaS:The trend matters more than the absolute number. A team whose MTTR is dropping quarter over quarter is getting better. A team with low MTTR that's been flat for a year may just be in a quiet period.-----## How to Actually Lower MTTRThree levers, each attacking a different part of the timeline:@@ -167,8 +157,6 @@ Most "we took too long to fix it" postmortems are actually "we took too long toThe teams that recover fastest aren't necessarily the smartest - they've practiced the recovery steps until they're muscle memory.-----## Common Mistakes**Reporting MTTR aggregated across severities.** A great MTTR for SEV3 hides a bad MTTR for SEV1. Always break down by severity.@@ -181,8 +169,6 @@ The teams that recover fastest aren't necessarily the smartest - they've practic**Ignoring the tail.** Reporting only the mean lets one bad outage hide in the data. Always look at P95 and P99.-----## How MTTR Connects to SLOsMTTR shows up directly in your [SLO budget math](/guides/sla-vs-slo-vs-sli).@@ -191,8 +177,6 @@ If your SLO allows 43 minutes of downtime per month (99.9%), and your MTTR is 60Lower MTTR effectively buys you more deployment risk. Each incident costs less budget, so you can take more chances. This is why mature teams obsess over MTTR - it's the most leveraged metric for reliability improvement.-----## The Bottom LineMTTR is the time from detection to recovery, averaged across incidents. It measures how good your team is at responding to and resolving outages.diff --git a/apps/web/src/content/pages/guides/what-is-synthetic-monitoring.mdx b/apps/web/src/content/pages/guides/what-is-synthetic-monitoring.mdxindex d2502510e..2e65e63e1 100644--- a/apps/web/src/content/pages/guides/what-is-synthetic-monitoring.mdx+++ b/apps/web/src/content/pages/guides/what-is-synthetic-monitoring.mdx@@ -29,8 +29,6 @@ Fake users, real signal. That's the trade synthetic monitoring makes - scripts tIt runs even when you have no traffic. It tests what you actually care about - the login flow, the checkout, the API endpoint your largest customer depends on - rather than waiting for someone to complain on Twitter.-----## How Synthetic Monitoring WorksA synthetic monitor is a script that runs on a schedule from your monitoring provider's infrastructure. The basic shape:@@ -42,8 +40,6 @@ A synthetic monitor is a script that runs on a schedule from your monitoring proThe check itself can range from "GET /healthz, expect 200" to "load the homepage, fill in the signup form, complete payment, verify the receipt email" - all driven by a script.-----## Types of Synthetic Checks### 1. HTTP / API Checks@@ -94,8 +90,6 @@ Tests the actual paths your customers integrate against. Catches problems whereEach fills a specific gap. Most teams use them sparingly.-----## Synthetic vs Real User Monitoring (RUM)Two complementary approaches to understanding service health:@@ -113,8 +107,6 @@ Synthetic answers "does this scenario work?" RUM answers "what are users actuallThey complement each other. Use synthetic to catch issues before users do; use RUM to understand the long tail of problems specific to particular devices, browsers, or regions.-----## When to Use Synthetic Monitoring**Use it when:**@@ -134,8 +126,6 @@ They complement each other. Use synthetic to catch issues before users do; use RThe thing to optimize: signal per monitor. Fewer well-chosen synthetic checks beat a dashboard full of redundant ones.-----## A Practical SetupA reasonable starting point for a mid-stage SaaS:@@ -149,8 +139,6 @@ That's roughly 10-15 monitors. Enough to catch real problems. Not so many that aFor multi-region coverage, run each from at least 3 geographically distributed locations and require majority failure before alerting.-----## Common Mistakes**Monitoring too many things.** Every monitor is an alert source. Every alert is an interruption. Be ruthless about pruning monitors that don't represent real customer impact.@@ -163,8 +151,6 @@ For multi-region coverage, run each from at least 3 geographically distributed l**Not updating scripts when the app changes.** Synthetic checks rot. A login flow check that's still using a deprecated form selector silently passes for weeks while users are actually broken. Treat synthetic scripts like code - review them, version them, update them when the underlying app changes.-----## The Bottom LineSynthetic monitoring is how you find out something is broken before your customers tell you. The investment pays off the first time a synthetic browser check catches a failed deploy that an HTTP check would have shown as healthy.diff --git a/apps/web/src/content/pages/guides/what-is-uptime-monitoring.mdx b/apps/web/src/content/pages/guides/what-is-uptime-monitoring.mdxindex 48304a5b3..49c9a5fcf 100644--- a/apps/web/src/content/pages/guides/what-is-uptime-monitoring.mdx+++ b/apps/web/src/content/pages/guides/what-is-uptime-monitoring.mdx@@ -29,8 +29,6 @@ Your internal dashboards say everything is fine. Your CPU graphs are flat. YourThis is the gap uptime monitoring exists to close. Send a request to your endpoint every minute from outside your own network, check the response, alert if something is wrong. The premise is simple. The interesting parts are in the details - what you check, how often, from where, and what counts as wrong.-----## How Uptime Monitoring WorksA monitoring service sits outside your infrastructure and makes synthetic requests to your endpoints on a schedule. The basic loop:@@ -52,8 +50,6 @@ The whole cycle repeats every 30 seconds to 5 minutes per monitor, from probe loMost teams use HTTP for the bulk of monitors and add browser checks for critical user paths like login or checkout.-----## Why External Monitoring MattersYour internal monitoring tells you when servers are unhealthy. It cannot tell you when your service is unreachable from your customers' networks.@@ -69,8 +65,6 @@ Common problems that only external monitoring catches:A server with green internal metrics can still be completely unreachable for users. External probes catch that gap.-----## What "99.9% Uptime" Actually MeansThe math, in case anyone asks:@@ -91,8 +85,6 @@ For the gory details on what these numbers actually buy you, see [why uptime perWant to compute the maximum downtime your SLA permits? Use our [uptime SLA calculator](/play/uptime-sla).-----## Choosing a Monitoring Frequency| Frequency | Use case |@@ -104,8 +96,6 @@ Want to compute the maximum downtime your SLA permits? Use our [uptime SLA calcuFaster isn't always better. At 10-second intervals you start measuring network noise more than service health. Your false positive rate climbs and your cost goes up. Default to 1 minute unless you have a specific reason to go faster.-----## Multi-Region MonitoringA single probe location lies to you. Networks fail. Probe servers have bad days. Bot detection rules sometimes catch monitoring traffic.@@ -114,8 +104,6 @@ The fix: run the same check from at least 3 regions on different continents, andIf two of three regions in different continents can't reach your service, something is genuinely wrong. If one of three can't, it's almost always a network issue on the probe side - not your problem.-----## What to MonitorDon't monitor everything. Monitor the things customers actually use.@@ -138,8 +126,6 @@ Don't monitor everything. Monitor the things customers actually use.Each monitor costs money and generates alerts. Keep the list lean and the signal high.-----## Uptime Monitoring vs Synthetic MonitoringUptime monitoring is the simplest form of [synthetic monitoring](/guides/what-is-synthetic-monitoring) - one request, one response, did it work. Synthetic monitoring is the broader category that includes:@@ -150,8 +136,6 @@ Uptime monitoring is the simplest form of [synthetic monitoring](/guides/what-isIf you only need to know whether your endpoints respond, uptime monitoring is enough. If you need to know whether complex user journeys work, you need full synthetic monitoring.-----## The Bottom LineUptime monitoring exists because you cannot trust your own infrastructure to tell you when it's unreachable. The whole point is the external perspective - what does this look like to a user in São Paulo right now?diff --git a/apps/web/src/content/pages/guides/why-every-saas-needs-a-status-page.mdx b/apps/web/src/content/pages/guides/why-every-saas-needs-a-status-page.mdxindex 04957a76b..4a2a34ce5 100644--- a/apps/web/src/content/pages/guides/why-every-saas-needs-a-status-page.mdx+++ b/apps/web/src/content/pages/guides/why-every-saas-needs-a-status-page.mdx@@ -21,8 +21,6 @@ faq:**TL;DR** - Status pages aren't a nice-to-have for SaaS products anymore. They're table stakes. Proactive communication reduces support load, retains customers during incidents, and builds trust that no marketing campaign can replicate. Not having one actively hurts your business.-----## You Will Have an OutageEvery SaaS has incidents. Your database will fail. Your API will return 500s. Your CDN provider will have an outage. AWS will go down and take half the internet with it.diff --git a/apps/web/src/content/pages/guides/why-uptime-percentage-is-misleading.mdx b/apps/web/src/content/pages/guides/why-uptime-percentage-is-misleading.mdxindex af46ef587..9a459dbbb 100644--- a/apps/web/src/content/pages/guides/why-uptime-percentage-is-misleading.mdx+++ b/apps/web/src/content/pages/guides/why-uptime-percentage-is-misleading.mdx@@ -41,8 +41,6 @@ We've built an uptime SLA calculator to help you understand the real impact.<ButtonLink href="/play/uptime-sla">Uptime SLA Calculator</ButtonLink>-----## "Available" ≠ "Usable"diff --git a/apps/web/src/content/pages/unrelated/not-found.mdx b/apps/web/src/content/pages/unrelated/not-found.mdxindex 9d33642e0..90873ba86 100644--- a/apps/web/src/content/pages/unrelated/not-found.mdx+++ b/apps/web/src/content/pages/unrelated/not-found.mdx@@ -11,7 +11,7 @@ category: "company"Are you looking for something specific?- [API Reference](https://api.openstatus.dev/v1)-- [Documentation](https://docs.openstatus.dev)+- [Documentation](/docs)- [Dashboard](https://app.openstatus.dev)- [Global Speed Checker](/play/checker)diff --git a/apps/web/src/content/pages/unrelated/pricing.mdx b/apps/web/src/content/pages/unrelated/pricing.mdxindex 017256457..ab1c18903 100644--- a/apps/web/src/content/pages/unrelated/pricing.mdx+++ b/apps/web/src/content/pages/unrelated/pricing.mdx@@ -72,15 +72,12 @@ faq:| Audit log | | + | + |----## EnterpriseFor teams that need more than what Scale offers — **SOC2 reports**, **SAML/SSO**, **custom regions**, **higher monitor and status page limits**, a **dedicated SLA**, custom contracts, and invoicing. We will tailor a plan to your requirements.<ButtonLink href="mailto:[email protected]">Contact us</ButtonLink>-----## Frequently asked questionsdiff --git a/apps/web/src/content/pages/unrelated/privacy.mdx b/apps/web/src/content/pages/unrelated/privacy.mdxindex 2acbb5c57..15463414b 100644--- a/apps/web/src/content/pages/unrelated/privacy.mdx+++ b/apps/web/src/content/pages/unrelated/privacy.mdx@@ -140,3 +140,7 @@ not charge a fee unless the request is manifestly unfounded or excessive.For privacy-related questions or to exercise any of the rights above, pleasecontact us at [email protected].++---++For how we protect data across these providers, see our [security page](/security).diff --git a/apps/web/src/content/pages/unrelated/registry.mdx b/apps/web/src/content/pages/unrelated/registry.mdxindex 8e2cc39c9..eedc32530 100644--- a/apps/web/src/content/pages/unrelated/registry.mdx+++ b/apps/web/src/content/pages/unrelated/registry.mdx@@ -80,8 +80,6 @@ Want to customize your theme?<ButtonLink href="https://themes.openstatus.dev" children="Go to Themes Explorer" />-----## Learn More- [Source Code Example](https://github.com/openstatusHQ/openstatus/tree/main/apps/web/src/content/shadcn-registry-example.tsx) - See all components in actiondiff --git a/apps/web/src/content/pages/unrelated/subprocessors.mdx b/apps/web/src/content/pages/unrelated/subprocessors.mdxindex 805496de2..8436689e1 100644--- a/apps/web/src/content/pages/unrelated/subprocessors.mdx+++ b/apps/web/src/content/pages/unrelated/subprocessors.mdx@@ -57,3 +57,5 @@ Openpanel:- Purpose: Product analytics- Location: EU++For how we protect data across these providers, see our [security page](/security).diff --git a/apps/web/src/content/sub-nav.tsx b/apps/web/src/content/sub-nav.tsxindex 3bf9e700f..69fc6de8a 100644--- a/apps/web/src/content/sub-nav.tsx+++ b/apps/web/src/content/sub-nav.tsx@@ -15,10 +15,13 @@ export function SubNav({ className, ...props }: React.ComponentProps<"div">) {className={cn("flex items-center justify-between gap-2", className)}{...props}>- <div className="prose px-4 text-muted-foreground">+ <div className="px-4 text-muted-foreground">{segments.map((segment, index) => (<Fragment key={segment}>- <Link href={`/${segments.slice(0, index + 1).join("/")}`}>+ <Link+ href={`/${segments.slice(0, index + 1).join("/")}`}+ className="ease transition-colors duration-150 hover:text-foreground motion-reduce:transition-none"+ >{segment.split("-").join(" ")}</Link>{index < segments.length - 1 ? (diff --git a/apps/web/src/content/toc.ts b/apps/web/src/content/toc.tsnew file mode 100644index 000000000..36fdaaa36--- /dev/null+++ b/apps/web/src/content/toc.ts@@ -0,0 +1,30 @@+import { slugify } from "./mdx-components/heading";++export type TocItem = { depth: 2 | 3; text: string; slug: string };++// Extract h2/h3 headings from raw MDX for the table of contents. Slugs are+// produced with the same `slugify` that `createHeading` uses at render time, so+// the TOC links resolve to the real heading ids. Fenced code blocks are skipped+// so `## comment` lines inside code don't leak into the TOC.+export function extractHeadings(source: string): TocItem[] {+ const items: TocItem[] = [];+ let inFence = false;++ for (const line of source.split("\n")) {+ const fence = line.match(/^\s*(```|~~~)/);+ if (fence) {+ inFence = !inFence;+ continue;+ }+ if (inFence) continue;++ const heading = line.match(/^(#{2,3})\s+(.+?)\s*#*\s*$/);+ if (!heading) continue;++ const depth = heading[1].length as 2 | 3;+ const text = heading[2].trim();+ items.push({ depth, text, slug: slugify(text) });+ }++ return items;+}diff --git a/apps/web/src/content/utils.ts b/apps/web/src/content/utils/index.tssimilarity index 71%rename from apps/web/src/content/utils.tsrename to apps/web/src/content/utils/index.tsindex 681a3ba61..49eb00eed 100644--- a/apps/web/src/content/utils.ts+++ b/apps/web/src/content/utils/index.ts@@ -1,87 +1,9 @@-import fs from "node:fs";import path from "node:path";-import matter from "gray-matter";-import slugify from "slugify";-import { z } from "zod";+import { getDocs } from "../docs";+import { type MDXData, getMDXDataFromDir, getMDXDataFromFile } from "./read";-// Structured data schemas-const howtoStepSchema = z.object({- name: z.string(),- text: z.string(),- image: z.string().optional(),- url: z.string().optional(),-});--const howtoSchema = z.object({- totalTime: z.string().optional(), // ISO 8601 duration format (e.g., "PT2H")- steps: z.array(howtoStepSchema),-});--const faqItemSchema = z.object({- question: z.string(),- answer: z.string(),-});--const metadataSchema = z.object({- title: z.string(),- publishedAt: z.coerce.date(),- description: z.string(),- category: z.string(),- author: z.string(),- image: z.string().optional(),- // Structured data fields- howto: howtoSchema.optional(),- faq: z.array(faqItemSchema).optional(),-});--export type Metadata = z.infer<typeof metadataSchema>;-export type HowToStep = z.infer<typeof howtoStepSchema>;-export type HowToData = z.infer<typeof howtoSchema>;-export type FAQItem = z.infer<typeof faqItemSchema>;--function parseFrontmatter(fileContent: string) {- const { data, content } = matter(fileContent);-- const validatedMetadata = metadataSchema.safeParse(data);-- if (!validatedMetadata.success) {- console.error(validatedMetadata.error);- throw new Error(`Invalid metadata: ${validatedMetadata.error.message}`);- }-- return { metadata: validatedMetadata.data, content };-}--function getMDXFiles(dir: string) {- return fs.readdirSync(dir).filter((file) => path.extname(file) === ".mdx");-}--function readMDXFile(filePath: string) {- const rawContent = fs.readFileSync(filePath, "utf-8");- return parseFrontmatter(rawContent);-}--function getMDXDataFromDir(dir: string, prefix = "") {- const mdxFiles = getMDXFiles(dir);- return mdxFiles.map((file) => {- return getMDXDataFromFile(path.join(dir, file), prefix);- });-}--function getMDXDataFromFile(filePath: string, prefix = "") {- const { metadata, content } = readMDXFile(filePath);- const slugRaw = path.basename(filePath, path.extname(filePath));- const slug = slugify(slugRaw, { lower: true, strict: true });- const href = prefix ? `${prefix}/${slug}` : `/${slug}`;- return {- metadata,- slug,- content,- href,- };-}--export type MDXData = ReturnType<typeof getMDXDataFromFile>;+export * from "./schema";+export type { MDXData } from "./read";export function getBlogPosts(): MDXData[] {return getMDXDataFromDir(@@ -217,6 +139,10 @@ export function getCustomerPage(slug: string): MDXData {);}+export function getDocPages(): MDXData[] {+ return getDocs();+}+export const PAGE_TYPES = ["blog","changelog",@@ -228,6 +154,7 @@ export const PAGE_TYPES = ["customers","guides","use-case",+ "docs","all",] as const;@@ -255,6 +182,8 @@ export function getPages(type: PageType) {return getGuides();case "use-case":return getUseCasePages();+ case "docs":+ return getDocPages();case "all":return [...getBlogPosts(),diff --git a/apps/web/src/content/listing.ts b/apps/web/src/content/utils/listing.tssimilarity index 76%rename from apps/web/src/content/listing.tsrename to apps/web/src/content/utils/listing.tsindex 1e4242bc1..3480dd7a8 100644--- a/apps/web/src/content/listing.ts+++ b/apps/web/src/content/utils/listing.ts@@ -1,3 +1,5 @@+import { getDocsPage } from "../docs";+import { docsNavTree, findDocsNode } from "../docs.config";import {type MDXData,formatDate,@@ -7,7 +9,7 @@ import {getCustomerPages,getGuides,getUseCasePages,-} from "./utils";+} from "./index";/*** Generates sitemap-style markdown listings for index and category pages@@ -21,6 +23,12 @@ export function generateListingForPath(pathname: string): string | null {return generateRootListing();}+ // Docs containers (hub, sections) have no backing MDX file — they render as+ // card grids; list their children from the nav tree. Leaves hit TIER 1.+ if (segments[0] === "docs") {+ return generateDocsListing(`/${segments.join("/")}`);+ }+const [category, subcategory, slug] = segments;// Index pages: /blog, /changelog, etc.@@ -136,3 +144,23 @@ function generateRootListing(): string {return `# OpenStatus Content\n\n${content}\n`;}++// List a docs container node's children. Any node in the tree with children is+// listable (hub lists sections, a section lists pages); leaves return null and+// fall through to their MDX file. Descriptions are resolved lazily per child.+function generateDocsListing(href: string): string | null {+ const node = findDocsNode(docsNavTree(), href);+ if (!node?.children?.length) return null;++ const intro = node.description ? `${node.description}\n\n` : "";+ const items = node.children+ .map((child) => {+ const description = child.slug+ ? getDocsPage(child.slug)?.metadata.description+ : undefined;+ return `- [${child.label}](${child.href})${description ? `: ${description}` : ""}`;+ })+ .join("\n");++ return `# ${node.label}\n\n${intro}${items}\n`;+}diff --git a/apps/web/src/content/utils/read.ts b/apps/web/src/content/utils/read.tsnew file mode 100644index 000000000..21f0a25e8--- /dev/null+++ b/apps/web/src/content/utils/read.ts@@ -0,0 +1,49 @@+import fs from "node:fs";+import path from "node:path";+import matter from "gray-matter";+import slugify from "slugify";+import { metadataSchema } from "./schema";++// `defaults` are merged under the file's frontmatter (file wins) before+// validation — lets callers supply fields the source omits (e.g. docs have no+// author/publishedAt) while still running the one shared schema.+export function parseFrontmatter(+ filePath: string,+ defaults?: Record<string, unknown>,+) {+ const { data, content } = matter(fs.readFileSync(filePath, "utf-8"));+ const parsed = metadataSchema.safeParse(+ defaults ? { ...defaults, ...data } : data,+ );+ if (!parsed.success) {+ console.error(parsed.error);+ throw new Error(`Invalid metadata in ${filePath}: ${parsed.error.message}`);+ }+ return { metadata: parsed.data, content };+}++function getMDXFiles(dir: string) {+ return fs.readdirSync(dir).filter((file) => path.extname(file) === ".mdx");+}++export function getMDXDataFromDir(dir: string, prefix = "") {+ return getMDXFiles(dir).map((file) =>+ getMDXDataFromFile(path.join(dir, file), prefix),+ );+}++export function getMDXDataFromFile(filePath: string, prefix = "") {+ const { metadata, content } = parseFrontmatter(filePath);+ const slugRaw = path.basename(filePath, path.extname(filePath));+ const slug = slugify(slugRaw, { lower: true, strict: true });+ const href = prefix ? `${prefix}/${slug}` : `/${slug}`;+ return {+ metadata,+ slug,+ content,+ href,+ filePath,+ };+}++export type MDXData = ReturnType<typeof getMDXDataFromFile>;diff --git a/apps/web/src/content/resolve.ts b/apps/web/src/content/utils/resolve.tssimilarity index 90%rename from apps/web/src/content/resolve.tsrename to apps/web/src/content/utils/resolve.tsindex 90a04dc73..d7a4ab50b 100644--- a/apps/web/src/content/resolve.ts+++ b/apps/web/src/content/utils/resolve.ts@@ -1,5 +1,5 @@-import { generateListingForPath } from "./listing";-import type { MDXData } from "./utils";+import { getDocsPage } from "../docs";+import type { MDXData } from "./index";import {getBlogPosts,getChangelogPosts,@@ -11,7 +11,8 @@ import {getToolsPages,getUnrelatedPages,getUseCasePages,-} from "./utils";+} from "./index";+import { generateListingForPath } from "./listing";/*** Content resolution result - either MDX content or a generated listing@@ -61,6 +62,11 @@ function resolveMdxContent(pathname: string): MDXData | null {}}+ // Docs use nested slugs (concept/x, sdk/nodejs/x) — resolve the full tail.+ if (segments[0] === "docs" && segments.length >= 2) {+ return getDocsPage(segments.slice(1).join("/")) ?? null;+ }+// Prefixed paths (category/slug format)const [category, slug] = segments;diff --git a/apps/web/src/content/utils/schema.ts b/apps/web/src/content/utils/schema.tsnew file mode 100644index 000000000..4a865bb68--- /dev/null+++ b/apps/web/src/content/utils/schema.ts@@ -0,0 +1,36 @@+import { z } from "zod";++// Structured data schemas+const howtoStepSchema = z.object({+ name: z.string(),+ text: z.string(),+ image: z.string().optional(),+ url: z.string().optional(),+});++const howtoSchema = z.object({+ totalTime: z.string().optional(), // ISO 8601 duration format (e.g., "PT2H")+ steps: z.array(howtoStepSchema),+});++const faqItemSchema = z.object({+ question: z.string(),+ answer: z.string(),+});++export const metadataSchema = z.object({+ title: z.string(),+ publishedAt: z.coerce.date(),+ description: z.string(),+ category: z.string(),+ author: z.string(),+ image: z.string().optional(),+ // Structured data fields+ howto: howtoSchema.optional(),+ faq: z.array(faqItemSchema).optional(),+});++export type Metadata = z.infer<typeof metadataSchema>;+export type HowToStep = z.infer<typeof howtoStepSchema>;+export type HowToData = z.infer<typeof howtoSchema>;+export type FAQItem = z.infer<typeof faqItemSchema>;diff --git a/apps/web/src/data/content.ts b/apps/web/src/data/content.tsindex b03a7918d..8c2e68a1f 100644--- a/apps/web/src/data/content.ts+++ b/apps/web/src/data/content.ts@@ -37,7 +37,7 @@ const resourcesFooterSection = {},{label: "Docs",- href: "https://docs.openstatus.dev",+ href: "/docs",},{label: "Guides",@@ -73,6 +73,10 @@ const useCasesSection = {const resourcesHeaderSection = {label: "Resources",items: [+ {+ label: "Docs",+ href: "/docs",+ },{label: "Customers",href: "/customers",@@ -81,10 +85,6 @@ const resourcesHeaderSection = {label: "Use Cases",href: "/use-case",},- {- label: "Docs",- href: "https://docs.openstatus.dev",- },{label: "Blog",href: "/blog",diff --git a/apps/web/src/styles/globals.css b/apps/web/src/styles/globals.cssindex 9eb8784ba..fec3a0987 100644--- a/apps/web/src/styles/globals.css+++ b/apps/web/src/styles/globals.css@@ -145,7 +145,7 @@}.prose a {- @apply text-foreground underline transition-all decoration-muted-foreground/50 underline-offset-2 decoration-2 hover:decoration-muted-foreground;+ @apply text-foreground underline decoration-muted-foreground/50 underline-offset-2 decoration-2 hover:decoration-muted-foreground transition-colors duration-150 motion-reduce:transition-none;}.prose .anchor:after {@@ -184,20 +184,24 @@@apply my-4 leading-7;}+.prose > p:first-of-type {+ @apply text-lg text-foreground/90 leading-8;+}+.prose h1 {- @apply text-balance text-3xl text-foreground font-medium tracking-tight my-6 relative;+ @apply text-balance text-3xl text-foreground font-semibold tracking-tight mb-6 relative;}.prose h2 {- @apply text-2xl text-foreground font-medium tracking-tight my-6 relative;+ @apply text-2xl text-foreground font-semibold tracking-tight mt-12 mb-4 pt-8 border-t border-border/60 relative scroll-mt-12;}.prose h3 {- @apply text-xl text-foreground font-medium tracking-tight my-6 relative;+ @apply text-xl text-foreground font-medium tracking-tight mt-8 mb-3 relative scroll-mt-8;}.prose h4 {- @apply text-lg text-foreground font-medium tracking-tight my-6 relative;+ @apply text-lg text-foreground font-medium tracking-tight mt-6 mb-2 relative scroll-mt-6;}.prose hr {@@ -227,7 +231,7 @@}.prose figure img {- @apply aspect-video object-cover border border-border;+ @apply aspect-video object-cover border border-border outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10;}.prose figure figcaption {@@ -239,16 +243,16 @@}.prose ul {- list-style-type: "- ";- @apply list-inside marker:text-muted-foreground;+ list-style-type: "– ";+ @apply list-outside pl-5 marker:text-muted-foreground;}.prose ol {- @apply list-inside list-decimal marker:text-muted-foreground;+ @apply list-outside pl-5 list-decimal marker:text-muted-foreground;}.prose li {- @apply leading-7;+ @apply leading-7 pl-1;}.prose details {diff --git a/packages/ui/package.json b/packages/ui/package.jsonindex ddf684746..8023a4ca3 100644--- a/packages/ui/package.json+++ b/packages/ui/package.json@@ -96,10 +96,11 @@"recharts": "catalog:","tailwind-merge": "catalog:","tailwindcss-animate": "catalog:",+ "vaul": "catalog:","zod": "catalog:"},"peerDependencies": {- "next-themes": "0.4.6",- "sonner": "2.0.5"+ "next-themes": "catalog:",+ "sonner": "catalog:"}}diff --git a/packages/ui/src/components/ui/drawer.tsx b/packages/ui/src/components/ui/drawer.tsxnew file mode 100644index 000000000..475173bd9--- /dev/null+++ b/packages/ui/src/components/ui/drawer.tsx@@ -0,0 +1,135 @@+"use client";++import type * as React from "react";+import { Drawer as DrawerPrimitive } from "vaul";++import { cn } from "@openstatus/ui/lib/utils";++function Drawer({+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Root>) {+ return <DrawerPrimitive.Root data-slot="drawer" {...props} />;+}++function DrawerTrigger({+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {+ return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />;+}++function DrawerPortal({+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Portal>) {+ return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;+}++function DrawerClose({+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Close>) {+ return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;+}++function DrawerOverlay({+ className,+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {+ return (+ <DrawerPrimitive.Overlay+ data-slot="drawer-overlay"+ className={cn(+ "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50 data-[state=closed]:animate-out data-[state=open]:animate-in",+ className,+ )}+ {...props}+ />+ );+}++function DrawerContent({+ className,+ children,+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Content>) {+ return (+ <DrawerPortal data-slot="drawer-portal">+ <DrawerOverlay />+ <DrawerPrimitive.Content+ data-slot="drawer-content"+ className={cn(+ "group/drawer-content fixed z-50 flex h-auto flex-col bg-background",+ "data-[vaul-drawer-direction=top]:inset-x-0 data-[vaul-drawer-direction=top]:top-0 data-[vaul-drawer-direction=top]:mb-24 data-[vaul-drawer-direction=top]:max-h-[80vh] data-[vaul-drawer-direction=top]:rounded-b-lg data-[vaul-drawer-direction=top]:border-b",+ "data-[vaul-drawer-direction=bottom]:inset-x-0 data-[vaul-drawer-direction=bottom]:bottom-0 data-[vaul-drawer-direction=bottom]:mt-24 data-[vaul-drawer-direction=bottom]:max-h-[80vh] data-[vaul-drawer-direction=bottom]:rounded-t-lg data-[vaul-drawer-direction=bottom]:border-t",+ "data-[vaul-drawer-direction=right]:inset-y-0 data-[vaul-drawer-direction=right]:right-0 data-[vaul-drawer-direction=right]:w-3/4 data-[vaul-drawer-direction=right]:border-l data-[vaul-drawer-direction=right]:sm:max-w-sm",+ "data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-3/4 data-[vaul-drawer-direction=left]:border-r data-[vaul-drawer-direction=left]:sm:max-w-sm",+ className,+ )}+ {...props}+ >+ <div className="mx-auto mt-4 hidden h-2 w-[100px] shrink-0 rounded-full bg-muted group-data-[vaul-drawer-direction=bottom]/drawer-content:block" />+ {children}+ </DrawerPrimitive.Content>+ </DrawerPortal>+ );+}++function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {+ return (+ <div+ data-slot="drawer-header"+ className={cn(+ "flex flex-col gap-0.5 p-4 group-data-[vaul-drawer-direction=bottom]/drawer-content:text-center group-data-[vaul-drawer-direction=top]/drawer-content:text-center md:gap-1.5 md:text-left",+ className,+ )}+ {...props}+ />+ );+}++function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {+ return (+ <div+ data-slot="drawer-footer"+ className={cn("mt-auto flex flex-col gap-2 p-4", className)}+ {...props}+ />+ );+}++function DrawerTitle({+ className,+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Title>) {+ return (+ <DrawerPrimitive.Title+ data-slot="drawer-title"+ className={cn("font-semibold text-foreground", className)}+ {...props}+ />+ );+}++function DrawerDescription({+ className,+ ...props+}: React.ComponentProps<typeof DrawerPrimitive.Description>) {+ return (+ <DrawerPrimitive.Description+ data-slot="drawer-description"+ className={cn("text-muted-foreground text-sm", className)}+ {...props}+ />+ );+}++export {+ Drawer,+ DrawerPortal,+ DrawerOverlay,+ DrawerTrigger,+ DrawerClose,+ DrawerContent,+ DrawerHeader,+ DrawerFooter,+ DrawerTitle,+ DrawerDescription,+};diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 9eb2b7c1e..2ea805dbc 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -567,6 +567,9 @@ catalogs:validator:specifier: 13.15.35version: 13.15.35+ vaul:+ specifier: 1.1.2+ version: 1.1.2zod:specifier: 4.1.13version: 4.1.13@@ -2899,7 +2902,7 @@ importers:specifier: 'catalog:'version: 16.2.6(@babel/[email protected])(@opentelemetry/[email protected])([email protected])([email protected]([email protected]))([email protected])next-themes:- specifier: 0.4.6+ specifier: 'catalog:'qr-code-styling:specifier: 'catalog:'@@ -2920,14 +2923,17 @@ importers:specifier: 'catalog:'sonner:- specifier: 2.0.5+ specifier: 'catalog:'tailwind-merge:specifier: 'catalog:'version: 3.6.0tailwindcss-animate:specifier: 'catalog:'version: 1.0.7([email protected])+ vaul:+ specifier: 'catalog:'+ version: 1.1.2(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])zod:specifier: 'catalog:'version: 4.1.13@@ -11658,12 +11664,6 @@ packages:resolution: {integrity: sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==}engines: {node: '>= 10.0.0', npm: '>= 3.0.0'}- resolution: {integrity: sha512-YwbHQO6cSso3HBXlbCkgrgzDNIhws14r4MO87Ofy+cV2X7ES4pOoAK3+veSmVTvqNx1BWUxlhPmZzP00Crk2aQ==}- peerDependencies:- react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc- react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc-resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}peerDependencies:@@ -12439,6 +12439,12 @@ packages:resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}engines: {node: '>= 0.8'}+ resolution: {integrity: sha512-ZFkClGpWyI2WUQjdLJ/BaGuV6AVQiJ3uELGk3OYtP+B6yCO7Cmn9vPFXVJkRaGkOJu3m8bQMgtyzNHixULceQA==}+ peerDependencies:+ react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc+ react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc+resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}@@ -22396,11 +22402,6 @@ snapshots:ip-address: 10.1.0smart-buffer: 4.2.0- dependencies:- react: 19.2.6- react-dom: 19.2.6([email protected])-dependencies:react: 19.2.6@@ -23128,6 +23129,15 @@ snapshots:+ [email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]):+ dependencies:+ '@radix-ui/react-dialog': 1.1.15(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])+ react: 19.2.6+ react-dom: 19.2.6([email protected])+ transitivePeerDependencies:+ - '@types/react'+ - '@types/react-dom'+dependencies:'@types/unist': 3.0.3diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex 5c1255b7b..6fa3dfc98 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -210,4 +210,5 @@ catalog:unified: 11.0.5unplugin-icons: 22.5.0validator: 13.15.35+ vaul: 1.1.2zod: 4.1.13