Skip to main content

Need2Watch Developer Documentation

Welcome to the Need2Watch API documentation. Need2Watch is an AI-powered change monitoring platform that lets you track web pages for changes using natural language.

What is Need2Watch?​

Need2Watch monitors web pages and notifies you when important changes occur. Unlike traditional monitoring tools that rely on brittle CSS selectors, Need2Watch uses Vision Language Models (VLMs) to understand page content visually.

Key Features​

  • Natural Language Monitoring: Create monitors with plain English like "Monitor iPhone 16 Pro price on Amazon"
  • AI-Powered Discovery: Automatically finds relevant pages and extracts the right data
  • Vision-Based Detection: No CSS selectors - adapts to layout changes automatically
  • Real-Time Webhooks: Get instant HTTP notifications when changes are detected
  • MCP Integration: First-class support for Model Context Protocol (Claude Desktop, Cursor, etc.)
  • Developer-First API: RESTful API with comprehensive OpenAPI 3.0 spec

⚡ Quickstart

Get your first monitor running in 5 minutes.

Get Started

📚 API Reference

Complete OpenAPI 3.0 specification with interactive docs.

View API Docs

🤖 MCP Integration

Integrate with Claude Desktop and other AI assistants.

Setup MCP

🍳 Recipes

Common patterns: price alerts, competitor tracking, and more.

View Recipes

Authentication​

Need2Watch supports two authentication methods:

curl https://api.need2.watch/v1/monitors \
  -H "X-API-Key: n2w_live_xxxxx"

Get your API key from app.need2.watch/settings/api-keys.

JWT Bearer Token​

# Login first
curl -X POST https://api.need2.watch/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "SecurePassword123!"
  }'

# Use the access token
curl https://api.need2.watch/v1/monitors \
  -H "Authorization: Bearer eyJhbGci..."

API Base URL​

All API requests use this base URL:

https://api.need2.watch/v1

Example: Create a Monitor​

curl -X POST https://api.need2.watch/v1/monitors \
  -H "X-API-Key: n2w_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "nlp",
    "intent": "Monitor iPhone 16 Pro price on Amazon",
    "sensitivity": 0.5,
    "checkIntervalSeconds": 3600
  }'

Response:

{
  "id": "mon-abc123",
  "name": "Monitor iPhone 16 Pro price on Amazon",
  "status": "active",
  "mode": "nlp",
  "source_count": 3,
  "created_at": 1706198400000,
  "interpreted_as": {
    "product": "iPhone 16 Pro",
    "metric": "price",
    "sites": ["amazon.com"]
  }
}

Rate Limits​

Free Tier​

  • 10 monitors maximum
  • 100 API requests per day
  • 15 minute minimum check interval

Full Tier​

  • Unlimited monitors
  • Unlimited API requests
  • 1 minute minimum check interval

See pricing for upgrade options.

SDKs and Libraries​

Official SDKs​

  • MCP Server (npm): npx -y @need2watch/mcp-server

Community SDKs​

Coming soon. Interested in building an SDK? Contact us at support@need2.watch.

Support​

OpenAPI Specification​

Download the complete OpenAPI 3.0 specification:

curl https://developers.need2.watch/openapi.json -o need2watch-openapi.json

Import into your favorite API client:

  • Postman: File > Import > need2watch-openapi.json
  • Insomnia: Preferences > Import/Export > Import Data > From File
  • Bruno: Import > OpenAPI

What's Next?​

  1. Quickstart Guide - Build your first integration
  2. API Reference - Explore all endpoints
  3. Recipes - Common use case examples
  4. MCP Setup - Integrate with AI assistants
  5. Webhooks - Real-time notifications
  6. Error Reference - Error codes and troubleshooting