DiffWatchQuickstart Guide

Get started with DiffWatch

You're 3 API calls away from monitoring any website for changes. Works with any language, any framework, any AI agent.

Get Your API Key

Create a free account and generate an API key from the dashboard.

1Sign up at diff.watch/dashboard

2Go to Settings → API Keys

3Click Create API Key and copy your key. That's it!

Your API key starts with dw_live_ — keep it secret, never expose it in client-side code.

Create Your First Monitor

One API call to start watching a URL for changes.

Create a monitor

bash

# Create a monitor that checks every hour
curl -X POST https://api.diff.watch/v1/monitors \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/pricing",
    "interval": "1h",
    "webhook_url": "https://your-app.com/webhook"
  }'

Response

json

{
  "id": "mon_a1b2c3d4",
  "url": "https://example.com/pricing",
  "status": "active",
  "interval": "1h",
  "next_check": "2025-01-01T01:00:00Z"
}

Supported intervals: 1m 5m 15m 30m 1h 6h 12h 24h. Minimum interval depends on your plan.

Want to try without code? Use the API Playground

Receive Webhooks

When a change is detected, DiffWatch POSTs a signed payload to your webhook URL.

Webhook payload — monitor.changed

json

{
  "event": "monitor.changed",
  "id": "evt_xxx",
  "created_at": "2025-01-01T01:05:00Z",
  "data": {
    "monitor_id": "mon_a1b2c3d4",
    "url": "https://example.com/pricing",
    "change_id": "chg_x9y8z7",
    "changes": {
      "added": ["Enterprise plan: $299/mo"],
      "removed": ["Enterprise plan: $199/mo"],
      "added_count": 1,
      "removed_count": 1,
      "summary": "Price changed from $199 to $299",
      "similarity": 0.95
    },
    "detected_at": "2025-01-01T01:05:00Z"
  }
}

Verify webhook signature

typescript

// Verify the X-DiffWatch-Signature header
import { createHmac } from "node:crypto"

function verifyWebhook(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret)
    .update(body).digest("hex")
  return signature === `sha256=${expected}`
}

Webhook payload fields

event — Always "monitor.changed"
data.changes.added / removed — Arrays of changed text lines
data.changes.summary — Human-readable description of changes
data.changes.similarity — 0 to 1 score (1 = identical, lower = bigger change)

TypeScript SDK

Install the official SDK for type-safe API access. Zero dependencies.

Install

bash

npm install @diffwatch/sdk

Usage

typescript

import { DiffWatch } from "@diffwatch/sdk"

const dw = new DiffWatch("dw_live_xxx")

// Create a monitor
const monitor = await dw.monitors.create({
  url: "https://example.com/pricing",
  interval: "1h",
  webhook_url: "https://your-app.com/webhook",
})

// List all monitors
const monitors = await dw.monitors.list()

// Get changes for a monitor
const changes = await dw.monitors.changes(monitor.id)

// Force an immediate check
await dw.monitors.check(monitor.id)

// Get the latest snapshot content
const snapshot = await dw.monitors.snapshot(monitor.id)

MCP Integration

Connect DiffWatch to AI assistants via the Model Context Protocol. Two modes available.

The MCP server lets AI agents like Claude, Cursor, and Windsurf create monitors, check changes, and manage webhooks directly. Choose the mode that fits your workflow:

Option A — StdioRequires API key

Runs locally via npx. Best for local AI editors like Claude Desktop and Cursor.

Claude Desktop — claude_desktop_config.json

json

{
  "mcpServers": {
    "diffwatch": {
      "command": "npx",
      "args": ["-y", "@diffwatch/mcp-server"],
      "env": {
        "DIFFWATCH_API_KEY": "dw_live_xxx"
      }
    }
  }
}

Cursor — .cursor/mcp.json

json

{
  "mcpServers": {
    "diffwatch": {
      "command": "npx",
      "args": ["-y", "@diffwatch/mcp-server"],
      "env": {
        "DIFFWATCH_API_KEY": "dw_live_xxx"
      }
    }
  }
}

Claude Code — Terminal

bash

claude mcp add diffwatch -- npx -y @diffwatch/mcp-server
# Set your API key in the env when prompted

Codex — Terminal

bash

codex mcp add diffwatch -- npx -y @diffwatch/mcp-server

Option B — Remote HTTPOAuth — no API key needed

Connects directly to the DiffWatch server. No local install, just browser login via OAuth. Works with any MCP-compatible client.

Claude Desktop — claude_desktop_config.json

json

{
  "mcpServers": {
    "diffwatch": {
      "type": "http",
      "url": "https://api.diff.watch/mcp"
    }
  }
}

Claude Code — Terminal

bash

claude mcp add --transport http diffwatch https://api.diff.watch/mcp

On first use, your AI client will open a browser window for login. After that, sessions persist automatically.

Available MCP tools

diffwatch_list_monitorsList all monitors with status

diffwatch_create_monitorCreate a new website monitor

diffwatch_get_changesGet detected changes for a monitor

diffwatch_check_nowForce an immediate check

diffwatch_get_snapshotGet the latest scraped page content

diffwatch_delete_monitorDelete a monitor and its history

API Reference

Full REST API with interactive examples.

Explore every endpoint in the interactive Swagger UI, powered by OpenAPI 3.1.

BASE URLhttps://api.diff.watch

AUTHx-api-key: dw_live_xxx

Endpoints

GET/v1/monitors— List monitors

POST/v1/monitors— Create monitor

GET/v1/monitors/:id— Get monitor

PATCH/v1/monitors/:id— Update monitor

DELETE/v1/monitors/:id— Delete monitor

GET/v1/monitors/:id/changes— List changes

POST/v1/monitors/:id/check— Force check

GET/v1/monitors/:id/snapshot— Get snapshot

Open API Reference API Playground

DiffWatch

Ready to start monitoring?

Create your free account and make your first API call in under 30 seconds. No credit card required.

Get Your API Key