API overview

Use the public API to manage monitors, snapshots, and webhooks programmatically.

Everything in the UI can also be automated through the public API.

Authentication

• Bearer tokens created in the dashboard.
• Send Authorization: Bearer <token> on every request.
• Rate limits apply per org and per endpoint.

Common endpoints

• POST /api/monitors to create a monitor.
• GET /api/monitors/{id}/diffs to fetch change history.
• POST /api/webhooks/worker/run to trigger test deliveries.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.diffmon.example.com/api/monitors

Errors

Errors include request IDs and machine-readable codes so you can retry or surface meaningful messages upstream.

Diff examples

When DiffMon detects a change, the diff response includes classification, severity, and per-path change details. These examples show what to expect when querying the API.

API monitor — schema change detected

A GET /api/monitors/{id}/diffs/{diffId} response for a JSON endpoint where the schema changed:

{
  "id": "dif_01JX8M79YQ",
  "monitorId": "mon_api_prices",
  "classification": "schema_change",
  "schemaChanges": 2,
  "valueChanges": 1,
  "topSeverity": "critical",
  "diffFingerprint": "sha256:7a8c…",
  "changes": [
    {
      "path": "$.items[*].price",
      "category": "schema",
      "op": "replace",
      "severity": "critical",
      "detail": "number → string"
    },
    {
      "path": "$.items[*].currency",
      "category": "schema",
      "op": "add",
      "severity": "medium"
    },
    {
      "path": "$.generatedAt",
      "category": "value",
      "op": "replace",
      "severity": "info"
    }
  ],
  "requestId": "req_9f8bc",
  "status": 200,
  "latencyMs": 210,
  "createdAt": "2026-02-11T10:15:31Z"
}

Key fields: classification tells you the overall change type, topSeverity is the highest severity across all changes, and each entry in changes gives path-level context. See Smart Schema Validation for the full severity model.

Website monitor — DOM change detected

A GET /api/monitors/{id}/diffs/{diffId} response for a website monitor using Browser Render:

{
  "id": "dif_01JX8P0MW2",
  "monitorId": "mon_site_pricing",
  "classification": "content_change",
  "summary": {
    "additions": 1,
    "removals": 1,
    "modifications": 2
  },
  "changedTargets": [
    "#app .hero h1",
    "link[rel='canonical']"
  ],
  "diffFingerprint": "sha256:4bc1…",
  "requestId": "req_6p2ad",
  "status": 200,
  "latencyMs": 480,
  "browserRender": true,
  "waitStrategy": "networkidle",
  "selector": "#app",
  "createdAt": "2026-02-11T10:15:31Z"
}

Website diffs include render context (browserRender, waitStrategy, selector) so you can reproduce the exact conditions that produced the change.

Webhook event envelope

When webhooks are configured, DiffMon delivers a diff.detected event with the same change data inside a signed envelope:

{
  "schemaVersion": "v1",
  "eventVersion": 1,
  "eventId": "evt_01JX8M7A2K",
  "eventType": "diff.detected",
  "occurredAt": "2026-02-11T10:15:31Z",
  "deliveredAt": "2026-02-11T10:15:32Z",
  "monitorId": "mon_api_prices",
  "diffId": "dif_01JX8M79YQ",
  "snapshotId": "snp_01JX8M6ZK0",
  "data": {
    "classification": "schema_change",
    "schemaChanges": 2,
    "valueChanges": 1,
    "changes": [
      {
        "path": "$.items[*].price",
        "category": "schema",
        "op": "replace",
        "severity": "critical"
      },
      {
        "path": "$.items[*].currency",
        "category": "schema",
        "op": "add",
        "severity": "medium"
      }
    ]
  }
}

Use eventId for idempotency and diffId to fetch the full diff via the API. See Webhooks for HMAC verification, retry schedule, and event types.

Browser Render via API

For JS-heavy website monitors, set browserOptions when creating or updating a URL monitor.

• Request field: browserOptions
• Stored/returned monitor field: browserOptionsJson

See Browser Render docs for valid option shapes, examples, and error codes.

Policy Rules via API

Policy rules are configured through monitor settings:

• GET /api/monitors/{id}/settings to read policyRulesJson
• PATCH /api/monitors/{id}/settings with policyRules to replace the full rule set

Use rules: [] to clear rules. Omit policyRules to leave stored rules unchanged. See Policy rules for rule schema and behavior.