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.
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,tcporheartbeatcheck 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
heartbeatcheck, 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-statusand 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:readto use the tools at all andstatus:writeto 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 |
Related
- Status page uptime checks, maintenance and subscribers: what each check kind does, limits and troubleshooting.
- Authentication and scopes and Errors, limits and pagination.