API and webhooks

API keys

Create keys under Account → API Keys → Create API key. Give it a name (for example Zapier or Production integration) and click Create. The key is shown once; copy it straight away. Keys look like sm_live_…. Delete a key with the trash icon on the same page; deleted keys stop working immediately.

A key acts for the whole workspace, so anyone holding it can read all monitors and trigger checks. Treat it like a password.

Making requests

Base URL: https://simrixmonitor.com/api/v1

Send the key as a Bearer token:

curl https://simrixmonitor.com/api/v1/monitors \
  -H "Authorization: Bearer sm_live_..."

Each key is limited to 100 requests per hour. Over the limit you get 429 until the window resets.

Endpoints

GET /monitors

Lists every monitor in the workspace.

{
  "object": "list",
  "data": [
    {
      "id": "…",
      "name": "Homepage price block",
      "type": "change",
      "url": "https://example.com/pricing",
      "active": true,
      "interval_minutes": 60,
      "last_status": "passed",
      "last_run_at": "2026-09-11T14:00:00.000Z",
      "site": { "id": "…", "name": "Example" }
    }
  ]
}

GET /monitors/{id}/runs?limit=20

Recent checks for one monitor, newest first. (The path and the JSON field names keep the older run spelling so existing integrations keep working.) limit defaults to 20, maximum 100. Each check has status, change_detected, change_significance, change_category, change_headline, annotation, ai_summary, failure_summary, duration_ms, http_status, screenshot_url, diff_screenshot_url, created_at, finished_at.

POST /monitors/{id}/trigger

Checks the monitor now and waits for the result.

{ "object": "run", "run_id": "…", "status": "passed", "change_detected": false }

Triggered checks follow the same rules as any other: a workspace whose billing needs attention gets 403. If another manual check is already in progress for the workspace you get 429; retry after it finishes. Triggered checks don't send alerts, by email, Slack or webhook.

Webhooks

Webhooks push events to a URL you control as soon as the check that produced them finishes. Add one under Account → Webhooks → Add webhook: give it a name, the endpoint URL, tick the events you want, and click Create webhook.

Events:

• change_detected: a change monitor found a significant change
• monitor_failed: a monitor failed
• monitor_recovered: a failing monitor passed again

Each webhook gets a signing secret, shown once when you create it. Use it to verify requests. Endpoints can be paused (Pause / Enable) or deleted from the list.

Request body

{
  "event": "monitor_failed",
  "timestamp": "2026-09-11T14:05:12.000Z",
  "workspaceId": "…",
  "monitor": { "id": "…", "name": "Checkout", "type": "click_check", "url": "https://example.com/product/mug/" },
  "run": {
    "id": "…",
    "status": "failed",
    "changeDetected": false,
    "aiSummary": "…",
    "failureSummary": "The item this check looks for was not on the page when the check finished.",
    "failureReasonCode": "element_missing",
    "failedStep": { "number": 5, "total": 5, "description": "The payment form appears" },
    "durationMs": 8421,
    "httpStatus": 200,
    "screenshotUrl": "https://simrixmonitor.com/api/artifacts/…",
    "diffScreenshotUrl": null,
    "shareUrl": "https://simrixmonitor.com/r/…"
  }
}

The check is under run, a name kept so existing integrations keep working. failedStep names the step a failed check stopped at, in the words the alert email and the check page use, and is null when the failure belongs to no step. shareUrl is the shareable report, present when the monitor includes one in its alerts. Branch on failureReasonCode, not on the wording of failureSummary, which can change.

Verifying the signature

Every request carries X-Simrix-Event (the event name) and X-Simrix-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body using your signing secret. Compute the same HMAC and compare with a constant-time comparison before trusting the request.

Each delivery is a single attempt with a 10-second timeout; there are no automatic retries, so make your endpoint accept quickly and process afterwards. Non-2xx responses are logged. Screenshot URLs in the request body require a signed-in workspace member to view.

Slack, Zapier, and friends

Slack has its own integration: connect a channel from Integrations and alerts are posted there, formatted for Slack (see Alerts to Slack). For anything else, point a webhook at a Zapier / Make catch-hook or at a tiny relay that formats the request body for its destination. Zapier and similar tools can also poll GET /monitors/{id}/runs with an API key.