WebSignal Developer DocumentationBuild, monitor, and integrate with the WebSignal platform

Welcome

WebSignal is a website monitoring and uptime platform that keeps you informed about the health, performance, and availability of your web services. Get alerted instantly when something goes wrong, track performance trends over time, and let AI agents manage your incident workflows.

This documentation covers the WebSignal REST API and the MCP (Model Context Protocol) AI integration server. Whether you’re building a custom dashboard, integrating alerts into your workflow, or connecting an AI assistant, you’ll find everything you need here.

Platform Features

Multi-Region Checks

Every monitor runs its checks from WebSignal’s home region, North Europe. On paid plans you can add further check regions per monitor, so each check runs independently from several parts of the world and you can see exactly how your service behaves for users in each geography.

How it works

• Choosing regions: Select regions when adding or editing a monitor, or via the API by supplying the API names from the table above in the enabledRegions field on POST /api/v1/monitor and PUT /api/v1/monitor/{id}. The home region is always active, doesn’t appear in enabledRegions, and doesn’t count against your allowance.
• Plan allowance: The number of additional regions scales with your plan: 0 on Starter, 2 on Growth, 5 on Pro, and 7 on Enterprise. A request that selects more regions than your plan allows is rejected with a client error.
• Reporting: The monitor report shows a latency line per region, a per-region breakdown of average, 95th, and 99th percentile response times, and a consolidated availability timeline. When some regions fail while others stay healthy the timeline marks the period as partial rather than down.
• First results: After enabling a new region, its first checks arrive within a few check intervals; until then the report notes that the region is awaiting its first checks.

Workspaces

Every monitor, incident, action group, and status page belongs to a workspace. A workspace is the unit of collaboration and of billing: members are invited into it with a role, and the plan of the workspace owner determines the limits that apply to everything inside it. A solo account still has a workspace, created automatically, so the model is the same whether or not you invite anyone.

Choosing the workspace for a request

Requests are resolved against exactly one workspace. Send the workspace’s id in the X-Workspace-Id header:

X-Workspace-Id: 0YYMZFSd5AA

If the header is absent, the API falls back to the workspace_id cookie, then to your only workspace when you belong to exactly one, and finally to the workspace you used most recently. Integrations should send the header explicitly rather than rely on the fallbacks, which exist for browser sessions. Use GET /api/v1/workspaces to list the workspaces you belong to and their ids.

Roles

Each member holds one role in the workspace, and every endpoint states the minimum role it requires.

A request below the required role answers 403 Forbidden with {"error":"insufficient_workspace_role"}; a request that resolves to no workspace at all answers 403 with {"error":"no_workspace_context"}.

Service Groups

Service Groups help you organize related checks for a single service or hostname. From an external API perspective, a monitor can belong to one Service Group at a time, and each Service Group can include up to four monitor capabilities: HTTP Availability, SSL Certificate, Latency, and DNS.

To reduce duplicate checks, each Service Group allows only one monitor per monitor type. For example, you can have one HTTP check and one DNS check in the same Service Group, but you cannot add two HTTP checks to that same group.

How to work with Service Groups

1. Create your first monitor for a URL using POST /api/v1/monitor.
2. Provide serviceGroupId when creating or updating monitors to attach them to a specific Service Group.
3. Use GET /api/v1/service-group to list group composition and monitor assignments.
4. Use PUT /api/v1/service-group/{id} to rename a service group.
5. Use POST /api/v1/service-group/{id}/move-monitors to move a set of monitors into another service group. The monitors keep running throughout, and you can optionally delete the source group in the same call once it’s empty.
6. Use DELETE /api/v1/service-group/{id} to request soft-delete of the group and any non-shared monitors.

Plans & Pricing

WebSignal offers tiered plans to match your monitoring needs. All paid plans include a 14-day free trial.

Plan Comparison

API Overview

The platform exposes two complementary interfaces: a REST API for traditional HTTP integrations and an MCP server for AI agent interoperability. Both share the same authentication model and underlying data.

Authentication

All APIs use OAuth 2.0 Bearer tokens issued by Auth0. Include the token in the Authorization header:

Authorization: Bearer <access_token>

Supported grant types:

• Authorization Code + PKCE: web and mobile applications
• Client Credentials: machine-to-machine integration
• Device Code: CLI and headless clients (including AI agents)

Endpoints require fine-grained domain.action scopes, a .read scope for GET endpoints and a .write scope for mutations, per resource domain: monitor, incident, statuspage, alert, account, and user. Standard user accounts hold all product scopes. See individual endpoint pages for specific scope requirements.

Getting Started

Choose the integration approach that fits your use case:

1. REST API: View the full endpoint reference to build custom dashboards, automate monitor management, or integrate alerts into your existing tools.
2. MCP / AI: Connect an AI assistant to query monitors, view incidents, and manage your monitoring setup through natural language.