Skip to content
Docs menu

Build on the Status page

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.

View .md

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

  • 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

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

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

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

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:

{ "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

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

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.

REST routes

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).

/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).

MCP 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