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
| Field | Type | |
|---|---|---|
target | object | Required. What to watch. Matching products |
conditions | object | Required. { "all": [...] } or { "any": [...] }, 1 to 10. Conditions |
where | object | Required. sites (1 to 10) and aggregate |
schedule | object | Required. every and until, optionally start_at and burst. Schedules |
notify | object | Where results go. Webhooks |
location | object | country, zip, radius, currency |
fetch | object | proxy and accept_site_terms |
then | object | A follow-up watcher. Follow-up watchers |
metadata | object | Your 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
| Field | Type | |
|---|---|---|
query | string | Required. A URL, an identifier or words, depending on match |
match | string | Required. url, sku, exact, line, category, listing |
attributes | object | Variant 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 |
exclude | string[] | Phrases that drop a product when they appear as whole words |
Condition
| Field | Type | |
|---|---|---|
field | string | Required. 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 |
op | string | Required. = != < <= > >= in not_in exists changed added removed judge |
value | any | A number, "$19.99", "10%", a date, a status, a list for in, or a rule in plain words for judge |
compare_to | string | first_snapshot, last_snapshot or window |
window | string | With compare_to: "window", how far back to compare, like "10m" |
over | object | key (sizes, dates, items), require (all, any, min_n), n, same (site, seller) |
where
| Field | Type | |
|---|---|---|
sites | string[] | Required. Hosts, repos, pages or URLs, or prefixed names like feed:, statuspage:, instatus: and change:. Sites |
aggregate | string | each (default), best, first, dedupe |
schedule
| Field | Type | |
|---|---|---|
every | string | Required. Like "15m", "1h" or "1d" |
until | string | Required. A date, "+30d", "after_first_match" or "never" |
start_at | string | When to run first, in ISO 8601. A time without an offset is UTC |
burst | object | near (release_date, opens_at) or at, plus window and every. Schedules |
notify
| Field | Type | |
|---|---|---|
channels | string[] | ["webhook"]. Set it with webhook, since each needs the other |
webhook | object | url (https) and events, with at least one of matched, changed, field_found, blocked, failing, recovered, ended, webhook_paused, clamped. Webhooks |
repeat | string | once, on_change (default), every_match |
cooldown | string | Shortest gap between sends. Default "6h" |
confirm | integer | 2 to 5. How many checks in a row must match before it fires. False matches |
location and fetch
| Field | Type | |
|---|---|---|
location.zip | string | A US ZIP. With radius, only places within that distance are kept |
location.radius | string | "25mi" or "40km" |
location.country | string | US |
location.currency | string | USD |
fetch.proxy | string | auto (default) or off |
fetch.accept_site_terms | boolean | Required for sites whose robots.txt or terms restrict automated access. It confirms you may fetch them under their terms. Sites |
Request
curl https://api.watcher.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"] } }
}'const watcher = await fetch('https://api.watcher.manwhas.shop/v1/watchers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SNAG_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'wool-runner-10',
},
body: JSON.stringify({
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'] } },
}),
}).then((response) => response.json());import os, requests
watcher = requests.post(
"https://api.watcher.manwhas.shop/v1/watchers",
headers={"Authorization": f"Bearer {os.environ['SNAG_KEY']}", "Idempotency-Key": "wool-runner-10"},
json={
"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"]}},
},
).json()
Response
201 Created
{
"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.
{
"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 | |
|---|---|
request | The whole corrected body, ready to send. Shortened here |
explanation | What looked wrong and what we changed, in plain sentences |
evidence | What 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.