Snag Watcher

API reference

Create a watcher

POST /v1/watchers

Creates a watcher and schedules its first run. It returns the watcher object, plus webhook_secret when notify has a webhook.

Body

FieldType
targetobjectRequired. What to watch. Matching products
conditionsobjectRequired. { "all": [...] } or { "any": [...] }, 1 to 10. Conditions
whereobjectRequired. sites (1 to 10) and aggregate
scheduleobjectRequired. every and until, optionally start_at and burst. Schedules
notifyobjectWhere results go. Webhooks
locationobjectcountry, zip, radius, currency
fetchobjectproxy and accept_site_terms
thenobjectA follow-up watcher. Follow-up watchers
metadataobjectYour own labels: up to 20 keys (40 characters each) with string values up to 500 characters. They come back on the watcher and in every event's data

target

FieldType
querystringRequired. A URL, an identifier or words, depending on match
matchstringRequired. url, sku, exact, line, category, listing
attributesobjectVariant filters, like { "size": 10, "color": "Black" }. A list matches any of its values. Some sites also take settings here (from, to, time_zone, party_size, selector, contains), which only tell the site what to fetch. Sites
excludestring[]Phrases that drop a product when they appear as whole words

Condition

FieldType
fieldstringRequired. price, price_drop, price_change, price_move, availability, quantity, version, release_status, release_date, date, opens_at, seller, kind, items, item, or an attribute. Conditions
opstringRequired. = != < <= > >= in not_in exists changed added removed judge
valueanyA number, "$19.99", "10%", a date, a status, a list for in, or a rule in plain words for judge
compare_tostringfirst_snapshot, last_snapshot or window
windowstringWith compare_to: "window", how far back to compare, like "10m"
overobjectkey (sizes, dates, items), require (all, any, min_n), n, same (site, seller)

where

FieldType
sitesstring[]Required. Hosts, repos, pages or URLs, or prefixed names like feed:, statuspage:, instatus: and change:. Sites
aggregatestringeach (default), best, first, dedupe

schedule

FieldType
everystringRequired. Like "15m", "1h" or "1d"
untilstringRequired. A date, "+30d", "after_first_match" or "never"
start_atstringWhen to run first, in ISO 8601. A time without an offset is UTC
burstobjectnear (release_date, opens_at) or at, plus window and every. Schedules

notify

FieldType
channelsstring[]["webhook"]. Set it with webhook, since each needs the other
webhookobjecturl (https) and events, with at least one of matched, changed, field_found, blocked, failing, recovered, ended, webhook_paused, clamped. Webhooks
repeatstringonce, on_change (default), every_match
cooldownstringShortest gap between sends. Default "6h"
confirminteger2 to 5. How many checks in a row must match before it fires. False matches

location and fetch

FieldType
location.zipstringA US ZIP. With radius, only places within that distance are kept
location.radiusstring"25mi" or "40km"
location.countrystringUS
location.currencystringUSD
fetch.proxystringauto (default) or off
fetch.accept_site_termsbooleanRequired for sites whose robots.txt or terms restrict automated access. It confirms you may fetch them under their terms. Sites

Request

Shell
curl https://api.watcher.staging.manwhas.shop/v1/watchers \
  -H "Authorization: Bearer $SNAG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wool-runner-10" \
  -d '{
    "target": { "query": "https://www.allbirds.com/products/mens-wool-runners", "match": "url", "attributes": { "size": 10 } },
    "conditions": { "all": [{ "field": "availability", "op": "=", "value": "back_in_stock" }] },
    "where": { "sites": ["allbirds.com"] },
    "schedule": { "every": "1h", "until": "+30d" },
    "notify": { "channels": ["webhook"], "webhook": { "url": "https://you.example/snag", "events": ["matched", "blocked"] } }
  }'

Response

201 Created

JSON
{
  "watcher_id": "wch_dhjqcvaqnhrchsnv7gtc",
  "kind": "availability",
  "status": "active",
  "parent_id": null,
  "request": { "target": { "query": "https://www.allbirds.com/products/mens-wool-runners", "match": "url", "attributes": { "size": 10 } } },
  "schedule": { "every": "1h", "next_run_at": "2026-11-04T19:38:44.390Z", "until": "2026-12-04T19:38:43.902Z" },
  "clamped": [],
  "warnings": [],
  "created_at": "2026-11-04T19:38:43.902Z",
  "last_run_at": null,
  "first_match_at": null,
  "last_snapshot": null,
  "events": [],
  "webhook_secret": "whsec_Qm9vcGllcy1hcmUtbm90LWEta2V5"
}

request is shortened here. It holds the full body you sent. If the body breaks a rule, you get 422 with every error at once. See Errors.

If a page is read by a learned recipe, we learn the recipe before the watcher is saved, so the first run already knows the page. If it can't be learned, you get 422 with recipe_not_learned.

Suggestions

On a 422, the body may include a suggestion: a corrected request we've validated and previewed. We never apply it, so send suggestion.request yourself if it's what you meant.

JSON
{
  "error": { "code": "site_cant_match", "message": "Any online store can't run a listing match. It supports: url, line, category.", "field": "where.sites[0]" },
  "errors": [{ "code": "site_cant_match", "message": "Any online store can't run a listing match. It supports: url, line, category.", "field": "where.sites[0]" }],
  "suggestion": {
    "request": { "target": { "query": "Q1", "match": "line" }, "where": { "sites": ["keychron.com"] } },
    "explanation": ["keychron.com can't run a listing match; a line match on \"Q1\" finds 7 products."],
    "evidence": { "found": 26, "matching_target": 7, "would_match_now": true, "sites": [{ "site": "keychron.com", "outcome": "ok", "found": 26, "matching_target": 7, "sample": [] }] }
  }
}
Field
requestThe whole corrected body, ready to send. Shortened here
explanationWhat looked wrong and what we changed, in plain sentences
evidenceWhat the suggestion's preview found: how many items, how many fit the target, and a few samples per site

There's no suggestion when we couldn't find a better request in time.