ServicePulse Docs

• Green — operational, no issues
• Yellow — degraded performance or partial outage
• Red — major outage or active incident

• Component scope — on the vendor page, select only the components or regions you watch (e.g. Snowflake regions, AWS AZs).
• Exclude / unless keywords — per vendor, add keywords that hide incidents (e.g. fedramp) and "unless" overrides (e.g. commercial, api).
• Ignore incident — dismiss a single incident; ServicePulse can suggest scope keywords with AI when you ignore.

Scoped incidents are hidden on your dashboard, excluded from alerts and SLA calculations, and filtered in the AI assistant. Vendor-wide status may still show degraded if other customers are affected — your effective view reflects scope.

• Draft a postmortem (markdown timeline + action items)
• Push the draft to a Notion page (if Notion is connected under Account → Integrations)
• Dispatch chat (Business) — ask questions and run live tools against your Connections (Dagster asset graph, Temporal workflows, Cloudflare zone health, GitHub, Airflow, MCP, and more)

Dispatch resolves tools by connection slug. Link connections to services on the Connections page so War Room knows which credentials apply during an incident.

Correlation signals: when Push or workflow failures arrive within 30 minutes of a vendor cluster, War Room attaches related push/workflow signals to the cluster and may raise confidence. Proactive playbooks auto-run list_connections and vendor discovery when you open a cluster (Business).

Unified service timeline: on My Services, expand a service to see vendor incidents, Push events, and ping failures from the last 7 days in one feed.

• Every incident separately — distinct alert per new incident; no vendor-level cooldown
• Smart grouping (default) — merge multiple new incidents from one poll into one alert; 20-minute cooldown before another new-incident alert on the same vendor/channel
• Maximum quiet — same poll merging with a 60-minute cooldown

Per-incident deduplication always applies — you won't get repeat alerts for the same incident. Skipped alerts from grouping show in Notif. History.

All channels apply to both vendor incidents and your own ping monitor alerts.

Verify the signature using HMAC-SHA256 with your webhook secret as the key. Use this to trigger runbooks, Slack bots, or incident management workflows.

• Out of incident scope or ignored incident
• No matching natural-language alert rule
• Quiet hours
• Deduplicated or merged duplicate update from the same vendor poll
• Vendor multi-incident grouping (when Alert grouping is not "Every incident separately")

Use this to debug why an alert didn't arrive — misconfigured webhooks, scope filters, and alert rules all show up here.

• Dagster deployment — GraphQL asset graph, orchestrator vendor discovery via watchedVendorSlugs; pair with Dagster+ Push webhooks for enriched alerts
• Temporal namespace — list recent workflow executions during incidents
• Cloudflare account — zone health and DNS/proxy status (distinct from tracking the Cloudflare vendor in My Stack for platform outages)

• ServicePulse Managed Proxy (recommended) — when you create a cloud connection without a BYO URL, we assign https://your-app/api/cloud-proxy/{token} automatically. Store GCP/Azure/AWS credentials as connection secrets; the token only identifies the connection.
• Bring your own proxy — deploy reference servers from integrations/cloud-proxies (Cloud Run, Azure Functions, Lambda) and paste the URL as executionsProxyUrl.

• A probe-config.json for private HTTP, Postgres, or shell-command checks
• Copy-paste steps for Docker, pip + cron, or Kubernetes CronJob

The open-source servicepulse-probe runs inside your VPC, checks private endpoints, and pings your heartbeat URL on success. ServicePulse never connects inbound to your network.

1. Connects with your existing drivers or CLI
2. Runs a health query (e.g. SELECT 1)
3. Pings the ServicePulse heartbeat URL if successful

• 24h and 90-day uptime percentages
• Average and p95 response time
• Response time chart (90 days)
• Day-by-day uptime calendar with 7/30/90d toggle
• Full incident log with duration and cause

• --bg — the status page background
• --fg — the status page text color
• --accent — the status page accent color

• .sp-status-page — top-level status page container
• .header — the page header area
• .service-item — each service card row
• .sp-overall-banner — overall status banner
• .sp-overall-banner-dot — status dot inside the overall banner
• .sp-overall-banner-label — banner label text
• .sp-maintenance-banner — maintenance banner (and children like ...-title, ...-item)
• .sp-maintenance-banner-title — maintenance banner title
• .sp-maintenance-banner-list — list container
• .sp-maintenance-banner-item — each maintenance entry
• .sp-maintenance-banner-link — “View all maintenance…” link
• .sp-incident-card — each incident details card (active + historical)
• .sp-incident-card--historical — historical incident card styling (Recent Updates)
• .sp-incident-summary — incident summary row (title + status badge + timestamp)
• .sp-incident-body — incident body shown when expanded
• .sp-incident-created-at — timestamp on the incident summary row
• .sp-incident-resolved-at — resolved timestamp (historical incidents)
• .sp-incident-status — incident status badge
• .sp-service-history — the 30-day history region inside each service card
• .sp-service-history-item — the service card wrapper when history is enabled
• .sp-service-history-summary — the summary row inside the service card
• .sp-service-name — service name text
• .sp-service-history-toggle — “30-day history” toggle text
• .sp-service-history-header — “Last 30 days” header row
• .sp-service-history-day — each 30-day day cell in the history strip
• .sp-service-history-days — strip/container for the day cells
• .sp-embed-snippet-toggle — “Embed this status page” summary
• .sp-embed-snippet-body — embed snippet body
• .sp-embed-snippet — the “Embed this status page” widget

• First ingest will upsert the metric and create the public chart configuration if needed.
• You can remove metrics from Status Page → Metrics; ingesting again may re-add them.

This is separate from vendor RSS (custom vendors with an RSS source URL), which ServicePulse polls on your vendor schedule like any other tracked vendor.

• A response time chart (avg and p95) with a 7/30/90-day toggle
• A day-by-day uptime calendar color-coded by worst status

• 24h and 90-day uptime percentages
• Average and p95 response time
• Response time chart (90 days)
• Day-by-day uptime calendar with a 7/30/90-day toggle

The first ingest auto-creates the metric. You can send a single object or an array of objects in one request.

• Surface API latency or error rate next to vendor status page health
• Correlate a Datadog monitor spike with a vendor incident timeline
• Compare product ping latency vs Datadog-reported latency for the same vendor

Series API (signed-in): GET /api/vendors/<slug>/metrics/<sourceId>/series?bucket=1d&agg=avg

The number of external metric sources you can connect depends on your plan. See Billing for limits.

• Native ServicePulse JSON (events + service status push)
• Atlassian Statuspage (incident & component_update webhooks)
• PagerDuty webhook v3
• Alertmanager (Prometheus)
• Datadog alert webhooks — fires when a monitor alert triggers or recovers
• New Relic alert webhooks — fires on policy condition state changes
• Dagster+ alert webhooks — fires on alert policy triggers
• Workflow platforms — n8n, Kestra, ZenML, Argo, Step Functions, Flyte, GCP Workflows, Azure Data Factory, dbt Cloud runs
• Jira Automation (outbound POST to your rule's URL)

1. Go to Push in the sidebar and click New Endpoint. Copy the generated URL.
2. In PagerDuty, open Integrations → Webhooks and add a new webhook pointing to that URL.
3. Select the event types you want forwarded (recommended: incident.triggered, incident.resolved, incident.acknowledged).
4. Save — ServicePulse will start receiving events immediately.

PagerDuty payloads are auto-detected as v3 format. No extra config required on the ServicePulse side.

Set send_resolved: true so ServicePulse can auto-resolve incidents when Alertmanager sends a resolved status.

1. Go to Alerts in your Dagster+ deployment.
2. Create or edit an alert policy. Under Notification channel, choose Webhook.
3. Set the webhook URL to your ServicePulse push endpoint:
   https://servicepulse.dev/api/ingest/<your-token>
4. Save the alert policy. ServicePulse will start receiving events immediately.

• alert_summary — short summary of the alert
• alert_content — full alert body
• alert_policy_name — name of the policy that fired
• alert_policy_id — policy ID
• alert_policy_description — policy description
• alert_id — unique ID for this alert instance
• deployment_name — Dagster+ deployment name
• deployment_url — URL to the deployment
• notification_type — type of notification
• is_sample — true when triggered by a test alert

The token in the URL is your push endpoint token — find it on the Push page. No Authorization header needed.

• Invite members by email (they receive a Clerk invite link)
• Assign roles: Admin or Member
• Remove members or revoke pending invitations

Admins can access billing, audit log, and org settings. Members can view and manage the shared vendor stack but cannot change billing or see the audit log.

• Open Account → Organization while in your org workspace
• In the organization profile, go to SSO
• Add a SAML connection and paste your IdP metadata (or use Clerk's setup wizard)
• Map attributes so email is required; test with a non-admin user before enforcing

Personal workspaces continue to use email/password or social login. SSO applies only to organization members after you enable it in Clerk.

• Vendor added or removed from tracking
• Ping monitor created, updated, or deleted
• Notification channel added or removed
• Status page settings changed
• API token created or revoked
• Push endpoint created or deleted
• Organization member invited or removed

In a personal workspace, you always see your own history. In an org, only admins (Clerk role org:admin) can access the audit log. Each entry shows the actor's name, email, action, and a timestamp.

Export via the in-app UI (CSV or JSON), or call GET /api/audit-log?format=csv with a browser session. For scripted access, use GET /api/v1/audit-log with a personal API token (personal workspace only — org audit log requires browser session).

• CommonPaper — sync signed agreements directly from your CommonPaper account
• Google Drive — index PDFs in a specified Drive folder
• Dropbox — pull contracts from a Dropbox folder

After connecting a source, ServicePulse parses SLA clauses (uptime percentage, measurement window, exclusions) and pre-fills the contract record. You review and confirm before it goes live.

• Dashboard widget shows estimated service credits (USD) parsed from contract remedy text when available
• Generate a draft vendor credit email with measured uptime evidence
• Track claim status: open → filed → resolved

• package.json / requirements.txt / go.mod — official SDK package names (e.g. stripe, @sendgrid/mail)
• Source code imports — SDK imports and API client instantiation patterns
• Environment variables — API key variable names (e.g. STRIPE_SECRET_KEY, TWILIO_ACCOUNT_SID)
• Config files — references to vendor hostnames and API base URLs

The built-in importer connects to the Statuspage Manage API using your existing API key and brings over everything — no CSV exports, no manual work.

• Components → Services — each Statuspage component becomes a service on your status page, in the same order.
• Incident history — historical incidents with original timestamps, status, and update bodies.
• Email subscribers — imported as unconfirmed; subscribers receive a one-time re-confirmation email (CAN-SPAM required) before going live.

Find the importer under Account → Import from Statuspage in the app sidebar, or go directly to /import/from-statuspage. Most migrations complete in under 2 minutes.

If you have scripts or CI pipelines that post to the Statuspage API, you can point them at ServicePulse with a one-line environment variable change. No code changes needed — ServicePulse accepts the same request shapes.

The compat shim supports Authorization: OAuth <key> (Statuspage format) and Authorization: Bearer <key> (ServicePulse format). Full endpoint list: API Reference → Statuspage compatibility shim.

The open-source integrations monorepo lives at github.com/servicepulsehq/integrations. It includes:

• Python servicepulse-client and typed JS/Go clients
• Orchestrator and CI integrations — Airflow, Dagster, Prefect (see libraries/ and examples/), plus GitHub Actions, GitLab, and Azure templates
• Terraform stack_health, GitOps samples, probe, webhooks

Use a Personal API token (sp_…) from Developers in the app. Vendors must be tracked in the same workspace the token was created for. Pipelines typically call GET /api/v1/tracked-vendors or GET /api/v1/stack-summary for a rolled-up health signal.

Pick the surface that matches your integration. Each section below documents request shape, auth, and query parameters.

• API Explorer (OpenAPI) — interactive reference (Swagger UI): try requests, request bodies, and Authorize for Bearer tokens
• Authentication — three token types (personal sp_..., status page posting key, push URL)
• Personal API — dashboard automation with a Bearer sp_... token; base path /api/v1 (see also open-source examples on GitHub)
• Public status & widgets — JSON for public pages (no token)
• Status page posting key — incidents, services, maintenance, and custom metrics for one page
• Statuspage.io compatibility shim — point existing Statuspage scripts at ServicePulse with one env-var change
• Push ingest — inbound webhooks to your account
• SLA breach report — export (browser session, Team+)
• Audit log export — CSV/JSON with a signed-in browser session (Team+)
• Audit log (personal API) — Team+; personal workspace tokens only
• Outbound webhooks — ServicePulse notifies your URL
• curl examples

• Personal API token — account-level Bearer token. Generate one under Developers in the sidebar. Pass as Authorization: Bearer sp_.... Use with the Personal API and the discovery endpoint GET /api/v1.
• Status page posting key — a Bearer token scoped to a single status page. Generate it under Developers → Status Page Posting Key. Use it for incidents, maintenance windows, and posting custom metrics — not for /api/v1.
• Push endpoint token — embedded directly in the ingest URL (/api/ingest/<token>). No Authorization header needed. Create one under Push in the sidebar.

Workspace scope: when you create a personal API token, it is bound to the workspace active in the app (personal account vs organization). Use a separate token per workspace if you automate both.

JSON API for scripts, CI, and integrations (mostly reads; create monitors via POST /api/v1/ping-targets). Auth: Authorization: Bearer sp_... (personal tokens from Developers, or Organization API tokens minted there when a Clerk org is active — same /api/v1 behavior, org-owned so automation survives member churn; org admins only). Discovery: GET /api/v1 returns the endpoint index as JSON.

Custom metric charts call GET /api/metrics/{id}/series with a browser session. Vendor APM charts (Datadog/New Relic) use GET /api/vendors/{slug}/metrics/{sourceId}/series. For automation, use GET /api/v1/metrics/{id}/series with a personal or organization API token.

Audit log (same Personal API) — response includes actor (name, email) per entry. Org-scoped tokens cannot use this endpoint; open Settings → Audit log in the app when an organization is active.

Connect ServicePulse to Cursor, Claude Desktop, eltPulse, or other MCP hosts. Use the hosted MCP at mcp.servicepulse.dev (Streamable HTTP + SSE, Authorization: Bearer sp_…) or run the stdio server locally. Tools wrap the Personal API.

Hosted (eltPulse / remote clients): URL https://mcp.servicepulse.dev, transport HTTP, header Authorization: Bearer sp_your_token.

1. Create a personal API token under Developers (sp_…).
2. Build the server: cd integrations/mcp-server && npm install && npm run build
3. Add to .cursor/mcp.json (see .cursor/mcp.json.example in the repo).

{
  "mcpServers": {
    "servicepulse": {
      "command": "node",
      "args": ["/path/to/servicepulse/integrations/mcp-server/dist/index.js"],
      "env": {
        "SERVICEPULSE_API_TOKEN": "sp_your_token",
        "SERVICEPULSE_BASE_URL": "https://servicepulse.dev"
      }
    }
  }
}

Tools include servicepulse_health_snapshot, servicepulse_stack_summary, servicepulse_list_incidents (with activeOnly, vendorSlug filters), servicepulse_create_ping_target, servicepulse_ask (Team+), and MCP resources at servicepulse://docs/getting-started. Remote hosts can use npm run start:http (Streamable HTTP + SSE on port 3100). Full list: integrations/mcp-server README.

When you are signed into the app, you can export the same audit log your org admins see (with org rules applied) without a Bearer token:

• GET /api/audit-log?format=json|csv — optional query params from, to, q, actionType, limit (max 2000), offset. Uses the session cookie; not an sp_... token.

GET /api/v1 lists the current discovery payload (including /api/v1/audit-log when deployed).

These endpoints work for public status pages only (isPublic in settings). No Bearer token.

• GET /api/status-page/<slug>/status — overall status, services, active incidents (JSON for dashboards and monitors).
• GET /api/widget/<slug>/status — CORS-enabled JSON for embeds; Cache-Control: public, max-age=60.
• GET /api/widget/maintenance/<slug>/status — upcoming / active maintenance for widgets; supports audience and leadMinutes query params.
• GET /s/<slug>/feed — RSS feed of public status page incident updates (no auth).

Heartbeat monitors (cron) use GET|POST /api/heartbeat/<token> — the token is in the path, not the posting key. With a personal API token, GET /api/v1/ping-targets returns heartbeatUrl for each heartbeat monitor so on-prem agents (for example the integrations probe) do not need copy-paste from the app.

One key (shown under Developers → Status Page Posting Key) authenticates write APIs for a single status page slug. It is not the same as a personal sp_... token.

• Incidents — create, update, resolve
• Services — list and update components
• Maintenance windows — list and schedule
• Custom numeric metrics — POST data points

The sections below follow that order: incidents, maintenance, and metrics are different APIs (different paths) that share the same posting key — maintenance is not a sub-resource of incidents.

Planned downtime is not created here — use the maintenance windows API next.

List and update services (components) on your status page programmatically. Useful for CI/CD pipelines that need to mark a service as degraded without creating a full incident.

All fields in the PATCH body are optional. Set active: false to mark a service as inactive (hidden from the status page). The id of each service is returned in the list — use that as serviceId.

If you have CI/CD scripts, Terraform configs, or automation that targets the Statuspage.io API, you can point them at ServicePulse with a one-line change. Replace https://api.statuspage.io with https://servicepulse.dev/api/compat/statuspage and use your ServicePulse posting key as the OAuth token.

The page ID used in URL paths can be either your status page slug (e.g. acme) or the numeric-style page ID returned by the GET /v1/pages discovery call.

Auth: use Authorization: OAuth <posting-key> (Statuspage style) or Authorization: Bearer <posting-key> (ServicePulse style) — both work.

Separate from the incidents API above: different paths (/maintenance vs /incidents). Same posting key Bearer token. List or schedule planned work on your status page.

limit is optional (1–100, default 50). Response includes maintenance array with window metadata.

audienceMode: inherit | public-only | internal-only.serviceIds must be valid service IDs on your page (empty array = no specific services).

POST numeric time-series points for metrics defined on your status page.

You can send a single object or an array of objects. Each item requires metric (key) and a numeric value.

• Native ServicePulse JSON
• Atlassian Statuspage (incident / component_update webhooks)
• PagerDuty webhook v3
• Alertmanager (Prometheus)
• Datadog alert webhooks — fires when a monitor alert triggers or recovers
• New Relic alert webhooks — fires on policy condition state changes
• Jira Automation (outbound POST to your rule's URL)

GET /api/sla/report — exports SLA breach analysis for a vendor and time window (slaBreachReports).

Query params: vendorId, window (monthly | quarterly | annual), periodStart (ISO date), optional format=csv.