# StatusPulse Agent API v1

StatusPulse is uptime monitoring and public status pages in one product. This API lets a coding agent (Claude Code, Cursor, any HTTP or MCP client) set up and run monitoring for a workspace: create status pages and probes, run the Setup Agent on a domain, read what's down, open and update incidents, and ask the incident copilot for the probable cause.

**An account is required.** The workspace Owner or an Admin creates an agent token in StatusPulse under **Pages → API tokens** — either **Create setup prompt** (a prompt with the token in it, to paste into you) or the **Agent token** switch. The token acts in that one workspace with Editor rights; the same plan limits apply as in the dashboard. If you don't have a token, ask the user to create one and give it to you. Never print it, commit it or put it in a URL.

Base URL `https://statuspulse.ai/agent/v1`. Bodies are JSON both ways. Every request sends `Authorization: Bearer sp_agent_…`.

## MCP

The same operations are an MCP server (Streamable HTTP) at `https://statuspulse.ai/mcp`, authenticated with the same header. In Claude Code:

```bash
claude mcp add --transport http statuspulse https://statuspulse.ai/mcp \
  --header "Authorization: Bearer $STATUSPULSE_AGENT_TOKEN"
```

Tools: `get_status`, `list_status_pages`, `create_status_page`, `list_probes`, `create_probe`, `delete_probe`, `scan_domain`, `apply_setup`, `list_incidents`, `open_incident`, `post_incident_update`, `analyze_incident`.

## Endpoints

| Method and path | Purpose |
|---|---|
| `GET /status` | What's down: pages with probe counts, failing probes with their last error, open incidents. Start here. |
| `GET /status-pages` | Status pages with public URL and probe counts. |
| `POST /status-pages` | Create a page: `{"name": "Acme status"}`. |
| `GET /probes?statusPageId=` | Probes with type, target, latest status, latency, error. |
| `POST /probes` | Create a probe (below). |
| `DELETE /probes/{id}` | Stop monitoring a probe. Ask the user first. |
| `POST /setup/scan` | Run the Setup Agent on a domain: `{"domain": "acme.com"}`. Returns proposed probes; creates nothing. |
| `POST /setup/apply` | Create the probes the user kept (below). |
| `GET /incidents?open=true` | Open incidents (`open=false`: the last 50). |
| `POST /incidents` | Open a public incident (below). Notifies subscribers. |
| `POST /incidents/{id}/updates` | Post an update: `{"message": "…", "state": "Monitoring"}`. Notifies subscribers. |
| `POST /incidents/{id}/analysis` | Incident copilot (Pro and Business): ranked causes with evidence, a draft update, who to page. |

## Create a probe

```bash
curl -X POST https://statuspulse.ai/agent/v1/probes \
  -H "Authorization: Bearer $STATUSPULSE_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "API", "type": "http", "target": "https://api.acme.com/health", "expectedStatus": "200"}'
```

| Field | Required | Notes |
|---|---|---|
| `name` | yes | Shown on the status page. |
| `type` | yes | `http` (target is a URL), `ping` (hostname), `tcp` (`host:port`), `ssl` (hostname — warns before the certificate expires), `dns` (hostname), `domain` (registrable domain — warns before it expires), `heartbeat` (no target). |
| `target` | yes, except heartbeat | See `type`. |
| `statusPageId` | no | Defaults to the oldest page. |
| `intervalSeconds` | no | Seconds between checks; the plan's minimum applies. For `heartbeat`, how often the job runs. |
| `expectedStatus` | no | HTTP only: `"200"` or `"200;204"`. |
| `public` | no | On the public status page (default `true`). Use `false` for `ssl`, `dns`, `domain`. |
| `dnsRecordType`, `dnsExpectedValue` | no | DNS only: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `CAA`, and a value the answer must contain. |

A `heartbeat` probe answers with `heartbeatUrl`: the user's cron job or worker must call it on every run. Show it to the user — it is returned only once.

Database, e-mail round-trip, WebSocket and gRPC probes take credentials, so they are created in the dashboard, not here.

## Set up monitoring for a domain

1. `POST /setup/scan` with the user's domain. The Setup Agent checks public DNS, certificates, usual subdomains (`app`, `api`, `status`, `docs`…) and health endpoints, and returns `candidates` with `type`, `target`, `name`, `group`, `showOnStatusPage`, `include` and a `reason`. It uses one of the workspace's daily scans (Free 3, Starter 5, Pro 20, Business 50).
2. Show the user the candidates with `include: true`.
3. `POST /setup/apply` with the ones they keep:

```json
{
  "statusPageId": null,
  "newPageName": "Acme status",
  "probes": [
    {"type": "Http", "target": "https://acme.com/", "name": "Website", "group": "Website", "public": true, "expectedStatus": "200"},
    {"type": "Ssl", "target": "acme.com", "name": "TLS certificate", "group": "Certificates & domain", "public": false}
  ]
}
```

It creates the page (or uses `statusPageId`), the component groups and the probes, stops at the plan's probe limit, and lists anything not created in `failures`.

## Incidents

```json
POST /incidents
{"statusPageId": "…", "title": "Elevated API errors", "severity": "Major", "message": "We're investigating errors on the API.", "affectedProbeIds": ["…"]}
```

`severity` is `Minor`, `Major` or `Critical`. Opening an incident and posting updates notify the status page's subscribers — confirm the wording with the user before you send it. `state` on an update moves the incident to `Identified`, `Monitoring` or `Resolved`.

## Errors

Every error is `{"error": "<code>", "message": "…"}`. The message says what to fix.

| HTTP | `error` | Meaning |
|---|---|---|
| 400 | `invalid_request` | Bad input, or a plan limit (probes, pages, probe type, interval). |
| 401 | `unauthorized` | Missing, wrong or revoked token. |
| 404 | `not_found` | No page, probe or incident with that id in this workspace. |
| 429 | | 120 requests a minute per token. Wait and retry. |

## What to tell the user

After creating probes, give the user the status page's public URL (`publicUrl` from `GET /status-pages`) and say the first results appear within a few minutes. If you created a heartbeat probe, give them its URL and where to call it.
