API documentation

Register merchant URLs, start scans and receive signed verdicts by webhook.

Authorization: Bearer kyw_live_YOUR_KEYon every request, from your serverManage API keys

How a scan reaches you

Everything is asynchronous. You register a URL once, start scans when you need one, and WatchURL pushes the verdict to your webhook. A periodic reconciliation call catches anything your endpoint missed.

Scroll sideways to see the whole flow.

Your serverWatchURL APIScan workerYour webhookScan pagesAI analysis, verdictp50 22sp95 ~130sPOST /url-profiles201 { id }POST /checks202 { check_run_id }queuedPOST check.completed (signed)200 within 5sGET /checks?since= (every 10-15 min)retries at +10s, +60s if your endpoint fails

Never block on a scan

Starting a scan returns 202 at once. Scans take 22s at the median and about 130s at p95.

Webhooks first

Push delivery is faster and uses none of your rate limit. Poll only if you cannot expose an endpoint.

Reconcile on a timer

List checks finished since your last sweep every 10-15 minutes so a missed webhook is never a missed verdict.

Code in
1

Create an API key and a webhook

Create a key under API keys and a webhook endpoint under Webhooks. Copy the webhook signing secret: you need it to verify every delivery. Keep both on your server only.

API keys are shown once. Never ship a key to a browser or mobile app; call WatchURL from your backend.
// .env on your server
WATCHURL_API_KEY=kyw_live_...
WATCHURL_WEBHOOK_SECRET=...   // from the Webhooks page

const WATCHURL = 'https://watchurl.ai/api/v1'
const headers = {
  'Authorization': 'Bearer ' + process.env.WATCHURL_API_KEY,
  'Content-Type': 'application/json',
}
2

Register the URL profile

Register each merchant URL once and store the returned id next to your merchant record. Pass your own id as external_id so webhooks can be matched back without a lookup table.

Use a category name from GET /api/v1/categories. Category matching compares against these names, so a free-text category weakens the mismatch check.
const res = await fetch(WATCHURL + '/url-profiles', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Acme Store',
    url: 'https://acme.com',
    declared_category: 'Retail & Shopping',
    check_frequency_hours: 24,      // or 'daily', 'weekly', 'monthly'
    max_pages: 3,
    external_id: merchant.id,       // your id, echoed back in webhooks
  }),
})
if (res.status === 402) throw new Error('URL profile limit reached for this plan')
if (!res.ok) throw new Error('Register failed: ' + res.status)
const { data: profile } = await res.json()
await db.merchants.update(merchant.id, { watchurl_profile_id: profile.id })

Response 201 Created

{
  "data": {
    "id": "8a2e…",
    "name": "Acme Store",
    "url": "https://acme.com",
    "external_id": "your-merchant-123",
    "declared_category": "Retail & Shopping",
    "status": "active",
    "check_frequency_hours": 24,
    "max_pages_per_check": 3,
    "created_at": "2026-10-09T08:52:58Z"
  }
}
3

Start a scan

Starting a scan returns 202 straight away. Mark the merchant as pending in your system and return to your user; do not hold a request open waiting for the verdict.

Scheduled profiles are scanned automatically at check_frequency_hours. You only call this for on-demand scans, such as at onboarding. Limit: 3/minute and 120/hour per organisation.
const res = await fetch(WATCHURL + '/checks', {
  method: 'POST',
  headers,
  body: JSON.stringify({ url_profile_id: profile.id }),
})

if (res.status === 409) {
  // Already scanning this profile: track that scan instead of starting another
  const { running_check_id } = await res.json()
  return running_check_id
}
if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') || 60)
  return queueForLater(profile.id, wait)   // see "Errors and retries"
}
if (!res.ok) throw new Error('Start scan failed: ' + res.status)

const { check_run_id } = await res.json()
await db.merchants.update(merchant.id, { status: 'pending_verification', watchurl_check_id: check_run_id })

Response 202 Accepted

{
  "success": true,
  "check_run_id": "c1f0…",
  "status": "queued",
  "pages_to_scan": 3,
  "message": "Check queued — results will appear within 30-60 seconds"
}
4

Receive the verdict by webhook

When the scan finishes WatchURL POSTs check.completed to your endpoint. Verify the signature, record the event id, reply 200, then act on the verdict in the background.

Reply within 5 seconds. WatchURL gives up on an attempt after 15s and retries, so slow handlers receive duplicates.
import crypto from 'crypto'

export async function POST(req) {
  const raw = await req.text()                       // verify the raw body, not re-serialised JSON
  const given = req.headers.get('x-watchurl-signature') || ''
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WATCHURL_WEBHOOK_SECRET)
    .update(raw)
    .digest('hex')
  const ok = given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
  if (!ok) return new Response('Invalid signature', { status: 401 })

  const event = JSON.parse(raw)

  // Retries reuse the same event_id: process each one once
  const firstTime = await db.webhookEvents.insertIfAbsent(event.event_id)
  if (!firstTime) return new Response('Duplicate', { status: 200 })

  await jobs.enqueue('handle-watchurl-event', event)  // do the work after replying
  return new Response('OK', { status: 200 })
}

// Background job
async function handleWatchurlEvent(event) {
  const { verdict, merchant, site_status } = event.data
  // The site itself could not be read: act on why, not on the verdict
  if (site_status.status === 'offline') return markMerchantOffline(merchant.external_id, site_status.message)
  if (site_status.status === 'blocked' || site_status.status === 'login_required') return queueManualReview(merchant.external_id, event.data)
  switch (verdict.result) {
    case 'PASS':   return activateMerchant(merchant.external_id)
    case 'REVIEW': return queueManualReview(merchant.external_id, event.data)
    case 'FAIL':   return holdMerchant(merchant.external_id, verdict.reason)
  }
}
5

Reconcile anything you missed

Webhooks can still be lost if your endpoint is down through every retry. Every 10 to 15 minutes, list checks that finished since your last sweep and process any you have not seen. The event-id check above keeps this safe to repeat.

If a scan you started has produced nothing after 10 minutes, fetch it with GET /checks/{id}. Scans with no progress are cancelled after 8 minutes, are not billed, and can be started again.
async function reconcile() {
  const since = await db.settings.get('watchurl_last_sweep')   // ISO time
  const startedAt = new Date().toISOString()

  const res = await fetch(WATCHURL + '/checks?limit=100&since=' + encodeURIComponent(since), { headers })
  const { data: checks } = await res.json()

  for (const check of checks) {
    if (await db.checksSeen.has(check.id)) continue
    if (check.status === 'completed') {
      const full = await fetch(WATCHURL + '/checks/' + check.id, { headers }).then(r => r.json())
      await handleCheckResult(full.data)
    } else if (check.status === 'failed' || check.status === 'blocked') {
      await markScanFailed(check.merchant_id, check.failure_reason)   // not billed; retry later
    }
  }
  await db.settings.set('watchurl_last_sweep', startedAt)
}