API & MCP

Your dashboards, their services and your URL monitors, as JSON for scripts, CI and wallboards, and over MCP for AI assistants. The catalog of status pages answers without a key; everything about your account needs one.

Getting a key

API keys come with Pro. Create one in Settings → API & MCP: give it a name, choose Read or Read & write, the dashboards it may see, and when it expires. The key is shown once; Stackpulse keeps only a fingerprint of it. Send it in the Authorization header of every request, never in the address:

Authorization: Bearer sp_live_…

A key sees only its dashboards and the URL monitors on them, never your billing, alert channels or account. A Read & write key can also add and remove services, and check, pause and resume URL monitors; nothing else. When Pro ends, keys are kept and work again after an upgrade.

Requests

Every endpoint is under https://stackpulse.app/api/v1 and answers JSON. Times are ISO 8601 in UTC. Services use the words online, issue, major_outage, critical, maintenance and unknown; URL monitors up, slow, down, paused and checking. Every item also has a color (green, yellow, orange, red, blue, grey), so one filter covers both.

curl -H "Authorization: Bearer $STACKPULSE_KEY" \
  https://stackpulse.app/api/v1/dashboards/k3v9x2m1q8w7e4r

{
  "id": "k3v9x2m1q8w7e4r",
  "name": "Production",
  "summary": "Cloudflare reports a major outage. The other 11 are running fine. …",
  "worst": "orange",
  "counts": { "green": 11, "yellow": 0, "orange": 1, "red": 0, "blue": 0, "grey": 0 },
  "items": [
    {
      "kind": "service",
      "id": "rg0ljsyle18kq60",
      "slug": "cloudflare",
      "name": "Cloudflare",
      "status": "major_outage",
      "color": "orange",
      "text": "Cloudflare One Clients are incorrectly challenged on some sites",
      "since": "2026-10-06T09:07:30.679Z",
      "url": "https://stackpulse.app/services/cloudflare",
      "statusPage": "https://www.cloudflarestatus.com/"
    },
    {
      "kind": "url",
      "id": "q7m2x9k4w1p8z3c",
      "name": "Lumen API",
      "display": "api.lumenlabs.dev/health",
      "status": "up",
      "color": "green",
      "text": "200 OK",
      "since": "2026-10-06T12:58:03.000Z",
      "responseMs": 184
    }
  ]
}

Endpoints

{ "services": ["github", "vercel"] }

The same as OpenAPI: /api/v1/openapi.json.

A deploy window

Wait for the vendors a release goes through, pause the API's monitor while it deploys, and always resume it. Name the vendors: a long regional outage somewhere else on the dashboard shouldn't hold every deploy.

# .github/workflows/deploy.yml
# STACKPULSE_KEY from the repository's secrets, DASHBOARD and MONITOR from its variables
- name: Vendors we deploy through are up
  run: |
    curl -sf -H "Authorization: Bearer $STACKPULSE_KEY" https://stackpulse.app/api/v1/dashboards/$DASHBOARD \
    | jq -e '[.items[] | select(.slug == "github" or .slug == "vercel")
             | select(.color == "orange" or .color == "red")] | length == 0'
- name: Pause the API's monitor
  run: curl -sf -X POST -H "Authorization: Bearer $STACKPULSE_KEY" https://stackpulse.app/api/v1/monitors/$MONITOR/pause
- name: Deploy
  run: ./deploy.sh
- name: Resume the API's monitor
  if: always()
  run: curl -sf -X POST -H "Authorization: Bearer $STACKPULSE_KEY" https://stackpulse.app/api/v1/monitors/$MONITOR/resume

AI assistants (MCP)

Stackpulse is also an MCP server, so Claude, ChatGPT, Cursor, VS Code and other assistants can answer “is it us or them?” from your dashboards. Its address is https://stackpulse.app/mcp (Streamable HTTP). In Claude and ChatGPT, add it as a custom connector; in Claude Code:

claude mcp add --transport http stackpulse https://stackpulse.app/mcp

Anyone can search the catalog and list outages. The first question about your dashboards asks you to sign in to Stackpulse, and the first change asks again before it’s made. Every account can connect an assistant to read, Free included; changes come with Pro. Clients that don’t sign in (Cursor, VS Code) send an API key instead: Settings → API & MCP has their setup. Dashboards and URL monitors can be named by name or id. The tools:

When a URL monitor is down, the tools list what else on the dashboard started having problems around then: a clue, never a cause.

Signing in, for client developers

OAuth 2.1 with PKCE (S256), as the MCP specification describes. A request to an account tool without a token gets 401 with WWW-Authenticate pointing at /.well-known/oauth-protected-resource/mcp, whose authorization server is https://stackpulse.app (/.well-known/oauth-authorization-server). Clients name themselves with a client ID metadata document: the client_id is its https address, and it lists where people may be sent back to. There’s no registration endpoint. Scopes are read and write; a read token asking for a change gets 403 insufficient_scope. Access tokens last an hour and work only at /mcp; refresh tokens rotate on every use, and a connection unused for 90 days is signed out.

Errors and limits

An error answers with { "error": { "code": "…", "message": "…" } }. Statuses change at most once a minute, so each key gets 60 requests a minute; past that the answer is 429 with Retry-After. To hear of changes as they happen, add a webhook in Notifications instead of polling.