ServicePulse Docs

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

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.

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.

• 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
• Correlate a Datadog monitor spike with a vendor incident
• Show your own service health metrics on your public status page

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

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

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

The in-app chart calls GET /api/metrics/{id}/series with a browser session. 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.

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.

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.