API reference

Preview a watcher

POST /v1/watchers/preview

Takes the same body as Create a watcher, runs every check once, and returns what each site gave and whether the conditions hold now. Nothing is saved. A preview takes as long as the slowest site, usually 1 to 5 seconds.

Request

Shell

curl https://watcher-api-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

JSON

{
  "kind": "availability",
  "schedule": { "every": "1h" },
  "clamped": [],
  "warnings": ["keychron.com has no extractor of its own; it's read as Any Shopify 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. No fields
`not_found`	The page is gone or isn't a product
`unreachable`	Timed out. Retried on the next run
`failed`	Couldn't be read; `detail` says why, such as `robots.txt disallows ...`

fields lists up to 50 candidates per site.