REST API Reference99 endpoints across 13 resource groups
Overview
| Property | Value |
|---|---|
| Base URL | https://api.websignal.io |
| API version | v1 |
| Content type | application/json |
| OpenAPI spec | https://api.websignal.io/swagger/v1/swagger.json |
| Health check | https://api.websignal.io/health |
All endpoints use the /api/v1/ prefix. Responses are JSON. Standard HTTP status codes indicate success (2xx), client errors (4xx), and server errors (5xx).
Authentication
Include an OAuth 2.0 Bearer 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
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 endpoints for specific requirements.
Choosing a workspace
Every resource belongs to a workspace, so each request is resolved against exactly one. Send its id in the
X-Workspace-Id header alongside your token:
Authorization: Bearer <access_token>
X-Workspace-Id: 0YYMZFSd5AA
Without the header the API falls back to the workspace_id cookie, then to your only workspace if
you belong to exactly one, then to the one you used most recently. Integrations should send it explicitly.
List your workspaces and their ids with GET /api/v1/workspaces, and see
Workspaces for the role model. Resources in another workspace answer
404 Not Found rather than 403, so an unexpected 404 usually means the request
resolved to a different workspace than you intended.
Monitors
Create, update, delete, and list website monitors. Each monitor tracks the availability and performance of a URL and can be associated to one service group.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/monitor | List all monitors for the authenticated user | monitor.admin |
| GET | /api/v1/monitor/{id} | Get a specific monitor by ID | monitor.admin |
| POST | /api/v1/monitor | Create a new monitor (optionally attach to a service group via serviceGroupId) | monitor.admin |
| PUT | /api/v1/monitor/{id} | Update an existing monitor, including service-group association and monitor types | monitor.admin |
| DELETE | /api/v1/monitor/{id} | Delete a monitor | monitor.admin |
| POST | /api/v1/monitor-test | Run a one-off HTTP availability test against a URL | monitor.admin |
| POST | /api/v1/monitor-test/ssl | Run a one-off SSL certificate test against a URL | monitor.admin |
| POST | /api/v1/monitor-test/dns | Run a one-off DNS resolution test against a hostname | monitor.admin |
Service Groups
Manage service groups used to organize monitors. A monitor belongs to one service group, and each service group supports at most one monitor per type (HTTP, SSL, Latency, DNS).
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/service-group | List service groups for the authenticated user | monitor.admin |
| GET | /api/v1/service-group/{id} | Get a specific service group by ID, including associated monitors | monitor.admin |
| PUT | /api/v1/service-group/{id} | Rename a service group | monitor.admin |
| POST | /api/v1/service-group/{id}/move-monitors | Move a set of monitors from this service group into another, optionally deleting the source group once empty; monitors keep running throughout | monitor.write |
| DELETE | /api/v1/service-group/{id} | Soft-delete a service group and schedule permanent purge after 90 days; non-shared monitors in the group are also soft-deleted | monitor.admin |
Workspaces & Members
Workspaces are the unit of collaboration and billing: every monitor, incident, action group, and status page belongs to one. Send X-Workspace-Id to choose the workspace a request applies to. Membership endpoints require Admin unless noted.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/workspaces | List the workspaces you belong to, with your role in each | account.read |
| PATCH | /api/v1/workspaces/{id} | Rename a workspace or update its settings (Admin) | account.write |
| GET | /api/v1/workspaces/{id}/members | List the members of a workspace with their roles and status | account.read |
| PATCH | /api/v1/workspaces/{id}/members/{memberId} | Change a member's role or suspend them (Admin) | account.write |
| DELETE | /api/v1/workspaces/{id}/members/{memberId} | Remove a member from the workspace (Admin) | account.write |
| PATCH | /api/v1/workspaces/{id}/members/me | Update your own notification preferences for this workspace | account.write |
| POST | /api/v1/workspaces/{id}/transfer-ownership | Transfer ownership to another member (Owner); the new owner's plan becomes the workspace's plan | account.write |
Invitations
Invite people into a workspace by email. The invited person receives a branded email with a time-limited link; accepting adds them with the role named on the invitation.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /api/v1/workspaces/{id}/invitations | Invite someone by email with a role (Admin) | account.write |
| GET | /api/v1/workspaces/{id}/invitations | List pending invitations for the workspace (Admin) | account.read |
| DELETE | /api/v1/workspaces/{id}/invitations/{invitationId} | Revoke a pending invitation (Admin) | account.write |
| POST | /api/v1/workspaces/{id}/invitations/{invitationId}/regenerate-link | Issue a fresh link for a pending invitation (Admin) | account.write |
| POST | /api/v1/invitations/accept | Accept an invitation with its token and join the workspace | account.write |
| POST | /api/v1/invitations/decline | Decline an invitation with its token | account.write |
Teams & On-Call
Teams group workspace members and own an on-call rotation. Assign service groups to a team and incidents on those monitors page whoever is on call at that moment rather than everyone. Reads require Viewer; create and delete require Admin. On-call rotations are available from Growth upward.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/teams | List the teams in the workspace | account.read |
| GET | /api/v1/teams/{id} | Get a team with its members | account.read |
| POST | /api/v1/teams | Create a team (Admin) | account.write |
| PATCH | /api/v1/teams/{id} | Rename a team or update its settings (Admin) | account.write |
| DELETE | /api/v1/teams/{id} | Delete a team (Admin) | account.write |
| POST | /api/v1/teams/{id}/members | Add a workspace member to the team | account.write |
| PATCH | /api/v1/teams/{id}/members/{userId} | Change a team member's team role | account.write |
| DELETE | /api/v1/teams/{id}/members/{userId} | Remove a member from the team | account.write |
| GET | /api/v1/teams/{id}/schedule | Get the team's on-call rotation and overrides | account.read |
| GET | /api/v1/teams/{id}/oncall | Get who is on call for the team right now | account.read |
| PUT | /api/v1/teams/{id}/schedule | Create or replace the team's on-call rotation (daily or weekly) | account.write |
| POST | /api/v1/teams/{id}/schedule/overrides | Add a one-off override covering a date range (a swap) | account.write |
| DELETE | /api/v1/teams/{id}/schedule/overrides/{overrideId} | Remove an override | account.write |
| GET | /api/v1/teams/{id}/service-groups | List the service groups routed to this team | account.read |
| PUT | /api/v1/teams/{id}/service-groups/{serviceGroupId} | Route a service group's incidents to this team | account.write |
| DELETE | /api/v1/teams/{id}/service-groups/{serviceGroupId} | Stop routing a service group to this team | account.write |
Monitor Data & Reports
Retrieve analytical data, reports, and historical metrics for a monitor.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/monitor/{id}/availability | Get availability data for a monitor | monitor.admin |
| GET | /api/v1/monitor/{id}/latency | Get latency analytics for a monitor | monitor.admin |
| GET | /api/v1/monitor/{id}/ssl-status | Get the latest SSL certificate status for a monitor | monitor.admin |
| GET | /api/v1/monitor/{id}/ssl-history | Get SSL certificate check history for a monitor | monitor.admin |
| GET | /api/v1/monitor/{id}/dns-history | Get DNS check history and schedule status for a monitor | monitor.admin |
| GET | /api/v1/monitor/{id}/incident | Get incidents associated with a monitor | monitor.admin |
| POST | /api/v1/monitor/{id}/report/generate | Generate a performance report for a monitor | monitor.admin |
Incidents
Query and manage incidents detected by your monitors. Incidents represent periods of downtime, SSL issues, latency spikes, or DNS problems.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/incident | List incidents with optional date range and pagination filters | monitor.admin |
| GET | /api/v1/incident/{id} | Get a single incident with full details and notes | monitor.admin |
| PATCH | /api/v1/incident/{id} | Update an incident (e.g. acknowledge) | monitor.admin |
Status Pages
Create and manage public status pages with grouped systems, optional custom banners, incident-history visibility controls, manual operator status overrides/messages, high-contrast visual status indicators, and 24-hour service-group health timelines.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/status-page | List status pages for the authenticated user | monitor.admin |
| GET | /api/v1/status-page/{id} | Get a status page by ID | monitor.admin |
| POST | /api/v1/status-page | Create a status page | monitor.admin |
| PUT | /api/v1/status-page/{id} | Update a status page | monitor.admin |
| DELETE | /api/v1/status-page/{id} | Delete a status page | monitor.admin |
| GET | /api/v1/status-page/{id}/incidents/{incidentPostId} | Get a status page incident post by ID | monitor.admin |
| POST | /api/v1/status-page/{id}/incidents | Create an operator-authored public incident/custom update post for a status page | monitor.admin |
| GET | /api/v1/public/status-page/{slug} | Get public status page data by slug (anonymous), including plan-gated service-group timeline samples with per-day uptime percentages and timeline window metadata (24h/7d/30d) | none |
Incident Notes
Add, update, and manage notes on incidents for postmortem tracking and team communication.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/incident/{incidentId}/notes | List all notes for an incident | monitor.admin |
| POST | /api/v1/incident/{incidentId}/notes | Create a new note on an incident | monitor.admin |
| PATCH | /api/v1/incident/{incidentId}/notes/{noteId} | Update an existing note | monitor.admin |
| DELETE | /api/v1/incident/{incidentId}/notes/{noteId} | Delete a note | monitor.admin |
Action Groups
Manage global action groups that define how you are notified when incidents occur. Action groups can be associated with multiple monitors and support email, SMS, and webhook alert channels.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/action-groups | List all action groups for the authenticated user with monitor counts | monitor.admin |
| GET | /api/v1/action-groups/{id} | Get a specific action group with associated monitor count | monitor.admin |
| DELETE | /api/v1/action-groups/{id} | Delete an action group | monitor.admin |
| POST | /api/v1/action-groups/{id}/monitors/{monitorId} | Associate an action group with a monitor | monitor.admin |
| DELETE | /api/v1/action-groups/{id}/monitors/{monitorId} | Disassociate an action group from a monitor | monitor.admin |
| POST | /api/v1/action-groups/email | Create an email action group | monitor.admin |
| GET | /api/v1/action-groups/email/{id} | Get an email action group by ID | monitor.admin |
| PUT | /api/v1/action-groups/email/{id} | Update an email action group | monitor.admin |
| GET | /api/v1/action-groups/sms/{id} | Get an SMS action group by ID | monitor.admin |
| PUT | /api/v1/action-groups/sms/{id} | Update an SMS action group | monitor.admin |
| POST | /api/v1/action-groups/webhook | Create a webhook action group | monitor.admin |
| GET | /api/v1/action-groups/webhook/{id} | Get a webhook action group by ID | monitor.admin |
| PUT | /api/v1/action-groups/webhook/{id} | Update a webhook action group | monitor.admin |
Monitor Alert Actions
Per-monitor alert action endpoints. These legacy endpoints manage alert actions scoped to a specific monitor. For new integrations, prefer the global Action Groups endpoints above.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/monitor/{monitorId}/action-groups | List all alert action groups for a monitor | monitor.admin |
| POST | /api/v1/monitor/{monitorId}/email-action-group | Create an email alert action | monitor.admin |
| GET | /api/v1/monitor/{monitorId}/email-action-group | List email alert actions | monitor.admin |
| GET | /api/v1/monitor/{monitorId}/email-action-group/{id} | Get a specific email alert action | monitor.admin |
| PUT | /api/v1/monitor/{monitorId}/email-action-group | Update an email alert action | monitor.admin |
| DELETE | /api/v1/monitor/{monitorId}/email-action-group/{id} | Delete an email alert action | monitor.admin |
| POST | /api/v1/monitor/{monitorId}/sms-action-group | Create an SMS alert action | monitor.admin |
| GET | /api/v1/monitor/{monitorId}/sms-action-group | List SMS alert actions | monitor.admin |
| DELETE | /api/v1/monitor/{monitorId}/sms-action-group/{id} | Delete an SMS alert action | monitor.admin |
| POST | /api/v1/monitor/{monitorId}/webhook-action-group | Create a webhook alert action | monitor.admin |
| GET | /api/v1/monitor/{monitorId}/webhook-action-group | List webhook alert actions | monitor.admin |
| PUT | /api/v1/monitor/{monitorId}/webhook-action-group | Update a webhook alert action | monitor.admin |
| DELETE | /api/v1/monitor/{monitorId}/webhook-action-group/{id} | Delete a webhook alert action | monitor.admin |
Users
Manage user accounts and profiles. User identity is linked to Auth0.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/user | Get the authenticated user's profile | user.read |
| GET | /api/v1/user/preferences | Get the authenticated user's persisted application preferences | user.read |
| POST | /api/v1/user | Create a new user account | user.create |
| PUT | /api/v1/user/{id} | Update a user profile | monitor.admin |
| PATCH | /api/v1/user/preferences | Update the authenticated user's persisted application preferences | edit:user |
| DELETE | /api/v1/user/{id} | Delete a user account | monitor.admin |
| GET | /api/v1/user/{userId}/trial | Get the user's trial status | monitor.admin |
| PUT | /api/v1/user/{userId}/trial | Update the user's trial | monitor.admin |
Products & Plans
Retrieve available subscription plans and pricing tiers.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/product | List all available products and plans | monitor.admin |