API reference
Preview a watcher
POST /v1/watchers/preview
It takes the same body as Create a watcher, checks every site once, and returns what each site gave and whether the conditions hold now. Nothing is saved. It takes as long as the slowest site, usually 1 to 5 seconds.
If nothing on any site fits the target, the preview can include a suggestion: a corrected request whose own preview found something. Finding one means trying other pages and match modes, which can add up to 45 seconds. We skip it when it couldn't help, like when robots.txt refuses the site or a site with built-in support answered with nothing. To skip the wait, like when a search box previews many sites at once, add ?suggest=false to the URL.
Request
curl https://api.watcher.staging.manwhas.shop/v1/watchers/preview \
-H "Authorization: Bearer $SNAG_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": { "query": "Q1", "match": "line" },
"conditions": { "all": [{ "field": "availability", "op": "=", "value": "in_stock" }] },
"where": { "sites": ["keychron.com"] },
"schedule": { "every": "1h", "until": "+7d" }
}'Response
200 OK
{
"kind": "availability",
"schedule": { "every": "1h" },
"clamped": [],
"warnings": ["keychron.com has no extractor of its own; it's read as Any online store. Check the preview before relying on it."],
"would_match": true,
"sites": [
{
"site": "keychron.com",
"url": "keychron.com",
"outcome": "ok",
"detail": "7 of 250 products kept",
"candidates": 26,
"matched": true,
"fields": [
{
"site": "keychron.com",
"url": "https://www.keychron.com/products/keychron-q1-he-qmk-wireless-custom-keyboard-iso-layout",
"title": "Keychron Q1 HE 8K Magnetic Switch Custom Keyboard (Japan JIS Layout)",
"attributes": { "type": "Fully Assembled", "color": "Black", "switches": "Keychron Ultra-fast Lime Magnetic Switch" },
"price": { "cents": 22999, "currency": "USD" },
"availability": "in_stock",
"release_status": "available"
}
],
"conditions": [{ "key": "keychron.com|...", "held": [true] }]
}
]
}outcome | Means |
|---|---|
ok | The site answered and was read |
blocked | A bot check or rate limit stopped it. No fields |
not_found | The page is gone or isn't a product, or the subreddit doesn't exist |
unreachable | It timed out, or (for a new subreddit) we're still collecting its first posts. The next run tries again |
failed | It couldn't be read. detail says why, like robots.txt disallows ... |
fields lists up to 50 candidates per site.
A preview also learns a recipe for a page without built-in support. The first time takes longer, since a model reads the page, and the site's detail says how many tries it took. Later previews and runs reuse the recipe.