---
title: Build on the Status page
description: Manage the public status page from code or an agent. Add uptime checks, read their results, schedule maintenance, edit the listed services and manage subscribers over REST or MCP.
section: developers
order: 110
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/status-pages/mcp.ts, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/app/api/status, services/nodejs-cloud/lib/status-pages/subscribers.ts]
features: []
---

The status page publishes uptime for your models and the services you check. Everything its settings page does with
checks, maintenance, services and subscribers is also an MCP tool and a REST route.

## What you can build {#build}

- **Checks from your deploy pipeline.** Create an `http`, `tcp` or `heartbeat` check for each new service (`POST /api/v1/status/checks`) and delete it when the service goes away.
- **Maintenance from your change calendar.** Schedule a window before a planned migration (`POST /api/v1/status/maintenance`), with alerts muted while it runs.
- **Uptime reports.** Read a check's runs and its last 24 hours of uptime and latency (`GET /api/v1/status/checks/{check}/results`) into your own dashboard.
- **A heartbeat for a nightly job.** Create a `heartbeat` check, keep its secret URL in your job, and have the job request it each time it finishes.
- **An agent that keeps the page tidy.** Connect `venom-status` and let an agent list stale checks, rename services and remove subscribers that bounce.

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/status`, server name `venom-status` |
| Connect | `claude mcp add --transport http venom-status https://cloud.usevenom.dev/workspace/mcp/status` |
| MCP tools | 16 (6 read, 10 write) |
| OAuth scopes | `status:read` `status:write` |
| REST twin | 16 routes under `https://cloud.usevenom.dev/api/v1` |
| Webhook events | `status.incident.created`, `status.incident.updated`, `status.incident.resolved`, `status.maintenance.scheduled`, `status.maintenance.started`, `status.maintenance.completed`, `status.component.changed` |

## Authentication and scopes {#scopes}

The page's settings belong to the organisation, so the caller's org role decides:

- A **personal API key** acts with its member's role. Owners and admins can change things; a viewer can only read.
- A **team key** has no member. It reads and is refused every change.
- An **OAuth app** needs `status:read` to use the tools at all and `status:write` to change anything, on top of the member's role.

A refused write answers `403` over REST, or a tool error that names the missing permission over MCP.

## Worked example {#example}

Add a website check that alerts after three failed runs, then read its results:

```bash
curl -X POST "$VENOM_CLOUD/api/v1/status/checks" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Website", "kind": "http", "url": "https://example.com/health", "component": "website", "fail_after": 3}'

curl "$VENOM_CLOUD/api/v1/status/checks/<check-id>/results?limit=20" \
  -H "Authorization: Bearer $VENOM_API_KEY"
```

The same over MCP, from any client connected to `/workspace/mcp/status`:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "status_check_create",
              "arguments": { "name": "Website", "kind": "http", "url": "https://example.com/health", "component": "website", "fail_after": 3 } } }
```

A `heartbeat` check's answer carries its secret URL once. Store it in your job's secrets and never log it.

## Events {#events}

7 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| Event | When |
|---|---|
| `status.incident.created` | An incident was published on the org's public status page: its title, impact, status, components and first update, as visitors see them. |
| `status.incident.updated` | A published status page incident got an update: its status and the update as posted on the page. |
| `status.incident.resolved` | A published status page incident was resolved. |
| `status.maintenance.scheduled` | A maintenance window was published on the status page: its title, times and components. |
| `status.maintenance.started` | A published maintenance window began. |
| `status.maintenance.completed` | A published maintenance window ended. |
| `status.component.changed` | A status page component (a model) went down or degraded, or is working again, as its automatic incidents see it: the component, its label, the new status (down, degraded, operational, or idle when it had no traffic) and the incident. |

Readers of the page follow it with their own webhooks instead: `POST /api/status/subscribe` with a slug and a URL
subscribes one, and it receives `status.incident.*` and `status.maintenance.*` deliveries signed like org webhooks.
See [Status page subscribers](/docs/cloud/status-page.md#subscribers).

## REST routes {#rest}

The REST twin: 16 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)).

**/status/checks**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/status/checks` | List the status page's uptime checks with their current state | `status_check_list` |
| POST | `/api/v1/status/checks` | Add an http, tcp or heartbeat check | `status_check_create` |
| GET | `/api/v1/status/checks/{check}` | Read an uptime check | `status_check_get` |
| PATCH | `/api/v1/status/checks/{check}` | Change, pause or rotate the secret URL of a check | `status_check_update` |
| DELETE | `/api/v1/status/checks/{check}` | Delete a check and its results | `status_check_delete` |
| GET | `/api/v1/status/checks/{check}/results` | A check's runs, newest first, with the last 24 hours' uptime and latency | `status_check_results` |

**/status/maintenance**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/status/maintenance` | List maintenance windows | `status_maintenance_list` |
| POST | `/api/v1/status/maintenance` | Schedule a maintenance window | `status_maintenance_create` |
| PATCH | `/api/v1/status/maintenance/{maintenance}` | Reschedule, reword, hide or end a window | `status_maintenance_update` |
| DELETE | `/api/v1/status/maintenance/{maintenance}` | Delete a maintenance window | `status_maintenance_delete` |

**/status/subscribers**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/status/subscribers` | Who follows the status page | `status_subscriber_list` |
| DELETE | `/api/v1/status/subscribers/{subscriber}` | Remove a subscriber | `status_subscriber_delete` |

**/status/components**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/status/components` | The services the status page lists | `status_component_list` |
| POST | `/api/v1/status/components` | List a service on the status page | `status_component_create` |
| PATCH | `/api/v1/status/components` | Rename a component or move it to a group | `status_component_update` |
| DELETE | `/api/v1/status/components` | Take a service off the status page | `status_component_delete` |

The admin API has the same operations under `/api/admin/v1/status-page` for operators who use an admin key
([Status page admin API](/docs/cloud/status-page.md#admin-api)).

## MCP tools {#tools}

16 tools: 6 read, 10 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `status_check_create` | Add an uptime check | write | `status:write` | `POST /api/v1/status/checks` |
| `status_check_delete` | Delete an uptime check | write (destructive) | `status:write` | `DELETE /api/v1/status/checks/{check}` |
| `status_check_get` | Read an uptime check | read | `status:read` | `GET /api/v1/status/checks/{check}` |
| `status_check_list` | List uptime checks | read | `status:read` | `GET /api/v1/status/checks` |
| `status_check_results` | Read a check's results | read | `status:read` | `GET /api/v1/status/checks/{check}/results` |
| `status_check_update` | Change an uptime check | write | `status:write` | `PATCH /api/v1/status/checks/{check}` |
| `status_component_create` | Add a component to the page | write | `status:write` | `POST /api/v1/status/components` |
| `status_component_delete` | Remove a page component | write (destructive) | `status:write` | `DELETE /api/v1/status/components` |
| `status_component_list` | List status page components | read | `status:read` | `GET /api/v1/status/components` |
| `status_component_update` | Change a page component | write | `status:write` | `PATCH /api/v1/status/components` |
| `status_maintenance_create` | Schedule maintenance | write | `status:write` | `POST /api/v1/status/maintenance` |
| `status_maintenance_delete` | Delete a maintenance window | write (destructive) | `status:write` | `DELETE /api/v1/status/maintenance/{maintenance}` |
| `status_maintenance_list` | List maintenance windows | read | `status:read` | `GET /api/v1/status/maintenance` |
| `status_maintenance_update` | Change a maintenance window | write | `status:write` | `PATCH /api/v1/status/maintenance/{maintenance}` |
| `status_subscriber_delete` | Remove a subscriber | write (destructive) | `status:write` | `DELETE /api/v1/status/subscribers/{subscriber}` |
| `status_subscriber_list` | List status page subscribers | read | `status:read` | `GET /api/v1/status/subscribers` |

## Related {#related}

- [Status page uptime checks, maintenance and subscribers](/docs/cloud/status-page.md): what each check kind does, limits and troubleshooting.
- [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md).
